Category : Dbase (Clipper, FoxBase, etc) Languages Source Code
Archive : BLIMAN15.ZIP
Filename : MANUAL.DOC
Output of file : MANUAL.DOC contained in archive : BLIMAN15.ZIP
Blinker Manual (c) 1990 Blink, Inc.
BLINKER
The High Performance Dynamic Overlay Linker
Version 1.5
Software and documentation
by
Jud Cole
Blink, Inc.
P.O.Box 7154,
Richmond,
VA 23221-0154.
Sales : (804) 355-4444
Support : (804) 353-0137
Fax. : (804) 355-1676
BBS : (804) 355-1111
1
Blinker Manual (c) 1990 Blink, Inc.
_________________________________________________________________________
| |
Table of Contents
| |
_________________________________________________________________________
| |
1. Introduction
1.1 Overview
1.2 System Requirements
1.3 Installation
1.4 Software License Agreement
1.5 Technical Support
1.6 Thanks
1.7 Trademark Acknowledgements
2. New Features in BLINKER 1.5
2.1 Overview
2.2 Incremental Linking
2.3 Clipper 5.0
2.4 Overlaying of 3rd Party Libraries
2.5 Memory Management Functions
3. Setting up the Environment
3.1 Overview
3.2 The PATH Variable
3.3 The OBJ Variable
3.4 The LIB Variable
3.5 The CLIPPER Variable
4. Setting up a Link Script File
4.1 Overview
4.2 Reduce the Number of Overlays and Areas
4.3 Ordering the Libraries
5. Understanding Overlays
5.1 Overview
5.2 Traditional Overlays - PLINK86plus
5.3 Dynamic Overlays - BLINKER
5.4 Choosing What to Overlay
2
Blinker Manual (c) 1990 Blink, Inc.
6. BLINKER Script Commands
6.1 Overview
6.2 Command Actions Table
6.3 # (comment)
6.4 ALLOCATE
6.5 BATCH
6.6 BEGINAREA
6.7 BLINKER DEBUG HANDLE
6.8 BLINKER DEMONSTRATION CALLS
6.9 BLINKER DEMONSTRATION DATE
6.10 BLINKER DEMONSTRATION MINUTES
6.11 BLINKER ENVIRONMENT NAME
6.12 BLINKER ENVIRONMENT OVERRIDE
6.13 BLINKER EXECUTABLE CLIPPER
6.14 BLINKER EXECUTABLE SERIAL
6.15 BLINKER INCREMENTAL FILE
6.16 BLINKER INCREMENTAL OFF
6.17 BLINKER INCREMENTAL PAD
6.18 BLINKER MEMORY PACK
6.19 BLINKER MESSAGE NOBLINK
6.20 BLINKER MESSAGE NOWARNING
6.21 BLINKER MESSAGE WINK
6.22 BLINKER OVERLAY OPSIZE
6.23 BLINKER PROCEDURE DEPTH
6.24 DEBUG
6.25 ENDAREA
6.26 FILE
6.27 HEIGHT
6.28 LIBRARY
6.29 LOWERCASE
6.30 MAP
6.31 NOBELL
6.32 OUTPUT
6.33 OVERLAY
6.34 SEARCH
6.35 SECTION
6.36 SECTION INTO
6.37 STACK
6.38 UPPERCASE
6.39 VERBOSE
6.40 WIDTH
6.41 WORKFILE
3
Blinker Manual (c) 1990 Blink, Inc.
7. BLINKER Programming Functions
7.1 Overview
7.2 BLICURCAL () - Current Procedure Calls
7.3 BLICURDSK () - Current Procedure Disk Loads
7.4 BLICURNME () - Current Procedure Name
7.5 BLICURSIZ () - Current Procedure Size
7.6 BLIDBGHAN () - Debug Handle
7.7 BLIDEMCAL () - Demonstration Calls
7.8 BLIDEMDTE () - Demonstration Date
7.9 BLIDEMMIN () - Demonstration Minutes
7.10 BLIDISFRG () - Display Fragmentation
7.11 BLIDISOVL () - Display All Overlays
7.12 BLIDISSTS () - Display Overlay Status
7.13 BLIDISTRC () - Display Call Trace
7.14 BLIERRNUM () - BLINKER Error Number
7.15 BLIERRPRM () - BLINKER Error Parameter
7.16 BLILSTFRG () - List Fragmentation
7.17 BLIMEMAVL () - Total Memory Available
7.18 BLIMEMBLK () - Memory Available in Blocks
7.19 BLIMEMMAX () - Maximum Memory Block Size
7.20 BLIMEMPAK () - Memory Pack Frequency
7.21 BLIMEMSIZ () - Total Memory Size
7.22 BLIMEMUSE () - Total Memory Used
7.23 BLIOVLCLR () - Clear Inactive Overlays
7.24 BLIOVLOPS () - Overlay Pool Operating Size
7.25 BLIOVLSIZ () - Overlay Pool Current Size
7.26 BLIPRFMOD () - Profiling Mode
7.27 BLISERNUM () - Serial Number
7.28 BLISTRFRG () - String of Fragmentation
7.29 BLITOTACT () - Total Active Procedures
7.30 BLITOTCAL () - Total Procedure Calls
7.31 BLITOTDSK () - Total Procedure Disk Loads
7.32 BLITOTLOD () - Total Loaded Procedures
7.33 BLITOTSIZ () - Total Procedure Size
8. Creating Demonstration Versions
8.1 Overview
8.2 Demonstration Call Limit
8.3 Demonstration Date Limit
8.4 Demonstration Time Limit
9. Getting More Out of BLINKER
9.1 Overview.
9.2 Incremental Linking During Development
9.3 Reduce the Number of Clipper OBJs
4
Blinker Manual (c) 1990 Blink, Inc.
9.4 Set the Clipper Environment Variable
9.5 Reduce Memory Fragmentation
9.6 Use the BLINKER Profiler
9.7 Enhance the BLINKER Error Handler
10. Using the BLINKER Profiler
10.1 Overview
10.2 Linking the Profiler to an Application
10.3 Interpreting the Results of the Profiler
11. The Future
11.1 Overview
11.2 Swapping Out of Memory to Disk
11.3 Expanded / Extended Memory
11.4 Compression of Clipper's Symbol Table
11.5 Multiple Language Support
11.6 Run Time Libraries
12. Error Messages
12.1 Overview
12.2 Link time Warning Messages
12.3 Link Time Fatal Messages
12.4 Run Time Error Messages
12.5 Other common errors
Glossary
Index
5
Blinker Manual (c) 1990 Blink, Inc.
_________________________________________________________________________
| |
1. Introduction
| |
_________________________________________________________________________
| |
1.1 Overview
_____________
BLINKER is a dynamic overlay linker which allows the Clipper developer
to easily and effectively overcome the 640KB limit imposed by DOS on
the personal computer.
Instead of having to structure an application into overlays which are
mutually exclusive and therefore may use the same area in memory at
run time, the developer simply specifies which procedures or
functions may be overlaid and leaves the rest to the BLINKER overlay
manager.
BLINKER performs the link phase of an application's compile and link
cycle, creating overlay units for the dynamic overlay manager and
linking the application in seconds rather than the minutes required by
conventional linkers. At run time this results in a simpler, more
compact program which uses less memory much more efficiently than with
traditional linkers.
By default BLINKER links incrementally, i.e once an application has
been linked then when changes are made to part of the application
BLINKER only relinks the part or parts which have changed. This
results in extremely fast link times for the majority of links, which
greatly speeds up the edit-compile-link-test development cycle.
BLINKER may also be used to prepare a demonstration copy of an
application at link time without modifying the application code in any
way. The demonstration program may be restricted either by the number
of procedure or function calls, by the number of minutes of execution
time, or by an expiration date after which the program will not run.
BLINKER provides profiling facilities allowing a user defined Clipper
procedure to be called each time any overlaid procedure is called,
without modification of the application source code. This allows the
developer to monitor an application while it is running and record
information such as how many times each overlay was called and how
many times it was loaded from disk.
Profiling allows the developer to isolate the critical procedures of
an application in order to optimise them to create a faster and more
efficient application. Large savings in memory and running speed of an
application can often be obtained by optimising one or two critical
6
Blinker Manual (c) 1990 Blink, Inc.
procedures or functions that have been identified using the profiling
tools.
The complete Clipper source code of an example profiler is provided on
the distribution diskette for the developer to use and modify as
required.
For a more detailed discussion of how BLINKER works and what it can do
for the developer, see Chapter 5, Understanding Overlays.
You will note that the majority of the manual is written for
applications which are large enough to require overlays to run in DOS.
Similarly, most of the BLINKER programming interface functions are
more appropriate for applications containing a significant proportion
of overlaid code.
BLINKER may also be used to quickly link programs without overlays in
exactly the same way as larger applications. BLINKER can reduce the
compile and link cycle for a small program under development to
fractions of a second, thus greatly reducing the development time of
even a small program.
For example, to link the small Clipper program TEST and create the
executable program TEST.EXE, type the following at the DOS prompt:
C> BLINKER FILE TEST LIB CLIPPER
The majority of the BLINKER commands may be used with non-overlaid
programs in the same way as with overlaid programs. The sections of
the manual detailing those which are only appropriate to overlaid
programs contain a note highlihting this fact.
1.2 System Requirements
________________________
The minimum requirements to run BLINKER are: IBM PC XT, AT, PS/2 or
compatible computer with a 10MB or larger hard disk, 512KB of RAM,
MS/PC DOS 2.1 or later and, of course, the Clipper Summer '87 or
Clipper 5.0 compiler from Nantucket.
1.3 Installation
_________________
BLINKER is supplied on one 5.25 inch or one 3.5 inch diskette and
consists of the following files:
3RDPARTY 3rd party library compatibility chart.
7
Blinker Manual (c) 1990 Blink, Inc.
BLINKER.EXE BLINKER itself.
READ.ME Last minute changes to the manual.
BLINKER.NG BLINKER Norton Guide database.
BLERRC50.PRG BLINKER Clipper 5.0 error handler.
BLERRPRG.PRG BLINKER Summer '87 error handler.
BLFRGPRG.PRG Sample BLINKER fragmentation display.
BLPRFPRG.PRG Default BLINKER profiling handler.
PRODEMO.LNK BLINKER profiler link script file.
PRODEMO1.PRG BLINKER profiler demo calling program.
PRODEMO2.PRG BLINKER profiler demo main program.
PROFILER.PRG BLINKER profiler program.
BLINKY.TXT Special documentation for FUNCky users.
To install BLINKER create a directory on your hard disk and copy the
contents of the diskette into the directory. Assuming your hard disk
is drive C: and the BLINKER diskette is in drive A:, type the
following at the C> prompt:
C> MD \BLINKER
C> CD \BLINKER
C> COPY A:\*.*
3RDPARTY contains a table of 3rd party add on libraries for Clipper
and details their compatibility with BLINKER. The table lists whether
the library may be overlaid or has to remain in the root, and gives
details of any updates to the libraries which are required. The latest
version of this file is available on the Blink, Inc. Technical Support
BBS : (804) 355-1111.
BLINKER.EXE is the program file which must be available in the PATH
environment variable - for a full discussion of the use of environment
variables, see Chapter 3, Setting Up the Environment.
READ.ME contains any last minute changes, corrections and information
which may have arisen since the manual went to press, and should be
8
Blinker Manual (c) 1990 Blink, Inc.
read before proceeding any further. It may be reviewed using any ASCII
editor or word processor, or displayed at the DOS prompt by typing:
C> TYPE READ.ME
If the file takes up more than one screen then press the Pause key or
Control-S to pause the display and press any other key to continue the
display. Information in the READ.ME file always takes precedence over
information in the manual.
BLINKER.NG is the BLINKER Norton Guide database which requires a
Norton Guide reader to display its contents. The Norton Guide reader
is distributed with Clipper 5.0
BLERRC50.PRG and BLERRPRG.PRG contain sample BLINKER error handlers,
the first for CLipper 5.0 and the second for Clipper Summer '87. The
appropriate error handler should ideally be placed in the ERRORSYS.PRG
file to link with each application. A compiled version of the
appropriate error handler is automatically linked to an application if
an alternative procedure of the same name is not present in the
application.
For more details on the error handler, see section 12.4, Run Time
Error Messages.
BLFRGPRG.PRG contains a sample program using the BLINKER function
BLIDISFRG () for use with Clipper Summer '87 to show the fragmentation
of memory after some simple string operations.
BLPRFPRG.PRG contains a sample BLINKER profiling handler which may be
placed anywhere in an application for the developer to perform
profiling of the application. This is the default profiler linked to
an application if a user defined function of the same name is not
included. This function displays the information available to the
profiling procedure, waits for the user to press a key and then
continues execution.
PRODEMO1.PRG and PRODEMO2.PRG contain a sample program to demonstrate
the profiler, PROFILER.PRG. PRODEMO.LNK is the BLINKER script file
used to create the profiler demonstration. All these files are heavily
commented and should be read in detail before attempting to use them.
For more details on profiling and the information available to the
profiling handler see Chapter 7 BLINKER Programming Functions.
BLINKY.TXT contains additional information for users of the FUNCky
add-on library for Clipper.
9
Blinker Manual (c) 1990 Blink, Inc.
1.4 Software License Agreement
_______________________________
1. Definitions
Software shall mean the computer program contained in the disks in
this package, together with any updates subsequently provided by
BLINK, Inc.
Documentation shall mean all of the printed materials provided in this
package or later supplied by BLINK, Inc.
Software Copies shall mean actual copies of all or any portion of the
Software and shall include updates and backups.
2. License
Blink, Inc. agrees to grant the user a non-exclusive and non-
transferable license to use the Software contained herein for an
unlimited duration. The rights granted herein are limited to use of
the Software, Software Copies, and Documentation as defined within the
Agreement. All rights not specifically granted in this Agreement are
reserved by Blink, Inc.
3. Permitted Uses
The Licensee may use the Software in the following ways:
load the Software into RAM and use it on a single workstation or
terminal;
install the Software onto a permanent storage device - a hard or
fixed disk drive;
make copies of the Software for backup purposes only, and the
Licensee must keep possession of them at all times.
4. Prohibited Uses
The Licensee may not:
Share the Software on a network. Each programmer must be an
original Licensee, i.e., must purchase a separate license to use the
Software from Blink, Inc.
Distribute copies of the Software or Documentation to others
Under any other circumstances attempt to rewrite, decompile, dis-
assemble or reverse-engineer any of the Software or Software copies.
10
Blinker Manual (c) 1990 Blink, Inc.
Reproduce, transmit, transcribe, store in a retrieval system, or
translate into any language the Documentation in any form by any means
without the written consent of the copyright holders.
5. Limitations
This license grants the user limited rights to use the Software,
Software Copies, and Documentation as expressly provided in this
license. Blink, Inc. retains title to all the Software, Software
Copies, and Documentation. The Licensee agrees to protect the
Software, Software Copies, and Documentation, from unauthorized
publication, use, reproduction or distribution.
6. Term
This license is effective from the date you receive the Software and
Documentation, and continues until you destroy the entire contents of
this package and any Software Copies.
This license will terminate if the Licensee fails to comply with any
term or condition of the Agreement. Upon such breach, Blink, Inc.
reserves the right to terminate the license and seek any remedies
which may be available to the company. Upon notice of termination,
the Licensee will be required to return all copies of the Software and
Documentation to Blink, Inc. In these circumstances the Licensee will
not be entitled to a refund of amount paid for the license to use the
Software and Documentation.
7. Limited Warranty
Blink, Inc. warrants to the original Licensee that the original
magnetic media is free from defects in material and workmanship under
normal use and service, for a period of thirty (30) days from date of
purchase as evidenced by your receipt or invoice. Blink, Inc.'s
entire liability and your exclusive remedy shall be replacement of the
defective disk, provided the disk is returned to Blink, Inc. with a
copy of your dated receipt or invoice.
Blink, Inc. shall not be liable to the Licensee or any other person
for any special, consequential, indirect or other similar damages or
claims including loss of profits, or any other commercial damage
caused or imagined to have been caused directly or indirectly by the
use of the Software. Blink, Inc. specifically disclaims all other
warranties, expressed or implied.
Blink, Inc. makes no representations or warranties with respect to the
merchantability or fitness of BLINKER for any particular purpose,
business or application. Implied warranties of merchantability are
11
Blinker Manual (c) 1990 Blink, Inc.
expressly and specifically disclaimed. In no event shall Blink, Inc.'s
liability for damages to you or any other person exceed the price paid
for the license to use the Software, regardless of the form of any
claim.
8. Updates and Revisions
Blink, Inc. reserves the right to modify and/or enhance BLINKER and
its documentation without obligation to notify any person or
organization of such changes. We recommend that you keep in touch on
our BBS regularly (see the sub-section entitled Electronic Mail in
section 1.5 Technical Support below).
9. Acknowledgement
You acknowledge that you have read this Agreement, understand it, and
agree to be bound by its terms and conditions. Furthermore, you agree
that this is the complete and exclusive statement of agreement between
us and supercedes all prior agreements, verbal or written, any
proposals and other communications between us relating to the subject
matter in this Agreement.
1.5 Technical Support
_____________________
Registration
____________
We offer free technical support in the U.S. and Canada as described
below to registered customers.
Please complete and mail the enclosed registration card to ensure you
are entitled to technical support.
Electronic Mail
_______________
Blink, Inc. provides unlimited technical support to registered users
in the U.S. and Canada via an electronic bulletin board service. The
BBS contains the latest technical support notes, messages from other
BLINKER users and files of general interest to developers.
Specific queries, problems or suggestions can also be directed to the
Sysops, either publicly or privately. Suggestions for improvements are
always welcome.
12
Blinker Manual (c) 1990 Blink, Inc.
The telephone number is (804) 355-1111 and supported baud rates are
1200 up to and including 9600, N 8 1. The BBS is on-line twenty-four
hours daily. Messages are usually answered within 24 hours.
Telephone
_________
Please make an honest effort to find the answer in the manual or on
our technical support BBS before you call. However, if you still are
having difficulties, you may contact us at (804) 353-0137 between the
hours of 0900 and 1700 Eastern Standard Time. Limited telephone
support will be provided free of charge to registered users for a
period of 90 days after registration for any questions directly
relating to BLINKER. Other than that, calls will be billed at the rate
of $100.00 US per hour with a $50.00 minimum per call.
U.S. Mail
_________
Letters are usually answered within 48 hours. Our address is:
Blink, Inc.
P.O.Box 7154
Richmond, Virginia 23221-0154
USA
Overseas
________
BLINKER distribution and support in Europe is handled by QBS, who may
be contacted as follows:
QBS
10 Barley Mow Passage,
Chiswick,
London
W4 4PH
ENGLAND
Technical Support:
13
Blinker Manual (c) 1990 Blink, Inc.
(081) 994-4842 VOICE
(081) 994-3441 FAX
Sales
(0279) 501510 VOICE
(0279) 501545 FAX
BLINKER distribution and support in Australia and New Zealand is
handled by RCM Software, who may be contacted as follows:
RCM Software,
51 Through Road,
Burwood,
Victoria,
3125
AUSTRALIA
(3) 809-2041 VOICE
(3) 889-0263 FAX
1.6 Thanks
__________
Special thanks to Jane without whom this would not have happened. Our
heartfelt thanks go to Greg Lief and Craig Yellick for a wonderful job
they did in helping us to bring you this product. Our sincere
gratitude also goes out to our tireless beta testing crew, as well as
the members of Compuserve NanForum for their many suggestions,
comments, and positive feedback.
1.7 Trademark Acknowledgements
______________________________
Clipper Nantucket Corporation.
CompuServe CompuServe Information Service.
14
Blinker Manual (c) 1990 Blink, Inc.
MS LINK Microsoft Corporation.
PLINK86plus Phoenix Technologies Ltd.
.RTLink PocketSoft Inc.
Norton Guides Peter Norton Computing.
Other brand and product names used in this document may be trademarks
or registered trademarks of their respective holders and are used for
identification purposes only.
15
Blinker Manual (c) 1990 Blink, Inc.
_________________________________________________________________________
| |
2. New Features in BLINKER 1.5
| |
_________________________________________________________________________
| |
2.1 Overview
_____________
This chapter summarizes the new features in version 1.5 of BLINKER.
2.2 Incremental Linking
_______________________
BLINKER 1.5 defaults to incremental linking mode, which can greatly
reduce the average link time of an application by only relinking the
parts of the application which have changed since the previous link.
In this version of BLINKER only Clipper compiled code may be
incrementally linked, changes to non-Clipper files will automatically
cause a full relink of the application.
The use of incremental linking is transparent during development as a
full link is forced only when necessary and is done so with no
intervention from the user. In practice it may be found that a full
link is only needed every five or ten links, thus greatly speeding
development.
Note: when using incremental linking the memory requirements of an
application may be increased slightly during development as space for
additions has to be left in the .EXE file. This overhead is relatively
small, however, is fully controllable by the developer, and may be
removed completely by setting a parameter to BLINKER.
Note: When performing an incremental link BLINKER only relinks the
changed .OBJs and does NOT perform any of the other functions
specified in the link file such as setting the CLIPPER environment
variable or the MEMORY PACK frequency. These values remain the same as
they were for the last full link. For BLINKER to perform these
functions a full link must be forced by deleting the .BIF file.
2.3 Clipper 5.0
_______________
BLINKER 1.5 now supports Clipper 5.0 along with complete backwards
compatibility to all the features provided by previous versions of
BLINKER for Clipper Summer '87.
Although Clipper 5.0 has changed significantly from the Summer '87
version of Clipper, the majority of BLINKER's features are still
applicable to Clipper 5.0 applications. In the few cases where a
16
Blinker Manual (c) 1990 Blink, Inc.
feature does not apply to Clipper 5.0 applications then that fact is
mentioned in the appropriate section of this manual.
2.4 Overlaying of 3rd Party Libraries
_____________________________________
BLINKER 1.5 contains greatly enhanced support for the overlaying of
3rd party libraries of non-Clipper compiled code, typically written in
C or ASM. The majority of the well known libraries are now overlayable
with BLINKER, and a compatibility chart is supplied on the
distribution diskette in the file 3RDPARTY.
For an up to date version of the file 3RDPARTY please feel free to
call and download it from our Technical Support BBS (804)-355-1111.
2.5 Memory Management Functions
_______________________________
The BLINKER 1.5 overlay manager contains a number of new functions to
further help with monitoring and improving the memory management of
your application under Clipper. These functions refer to the heap,
free pool or dynamic memory which Clipper uses at run time to maintain
the values of variables and functions used in the application.
These functions are detailed in Chapter 7 - BLINKER Programming
Functions, and include functions to obtain the size of the largest
contiguous block available in dynamic memory, the total size of
dynamic memory, and the total amount of dynamic memory available.
17
Blinker Manual (c) 1990 Blink, Inc.
_________________________________________________________________________
| |
3. Setting up the Environment
| |
_________________________________________________________________________
| |
3.1 Overview
_____________
DOS environment variables are used to pass information to applications
when they execute. This means that the information for the application
does not need to be included on the command line or in parameter
files. Space for the environment variables is allocated by DOS at boot
up time, so if a message stating that insufficient environment space
is available appears, then include the following line in your
CONFIG.SYS file and then reboot your computer:
SHELL=C:\COMMAND.COM /P /E:n
The SHELL command tells DOS which program to use as the command
interpreter to display the DOS prompt and execute DOS commands such as
copy etc.
The /P parameter indicates to COMMAND.COM that it is to be permanent,
i.e. that it is not a secondary copy loaded by another application.
The /E:n parameter indicates to COMMAND.COM the number of bytes (or,
in DOS 3.1, the number of 16-byte paragraphs) to be used for the
environment variables. This should be set to a large enough value to
accommodate the environment variables and their settings detailed
below. To create an environment variable, type SET followed by the
variable name directly followed by an = and the value to set it to.
For example, DOS itself uses the PATH environment variable as a list
of directories to search for a program or command which is typed at
the DOS prompt, with each path separated by a semi-colon. To inform
DOS to look first in the root C:\ and then in the C:\BLINKER directory
for a command you would type:
SET PATH=C:\;C:\BLINKER;
at the DOS prompt.
Environment variables may also be set in a batch file, such as
AUTOEXEC.BAT, by including the line exactly as typed at the DOS
prompt.
3.2 The PATH Variable
______________________
18
Blinker Manual (c) 1990 Blink, Inc.
The PATH environment variable must be set to include the directory in
which BLINKER is installed, as shown above. The program file
BLINKER.EXE must be in one of the directories specified in the PATH.
3.3 The OBJ Variable
_____________________
The OBJ environment variable may be set to a list of paths in the same
way as PATH to inform BLINKER where to find the .OBJ files specified
in the script file if they are not in the current directory. This
might be used to specify alternative directories where certain OBJ
files are kept out of the way, or a directory on a RAM disk to improve
performance, or to save repeating the path for each .OBJ file to be
linked.
3.4 The LIB Variable
_____________________
The LIB environment variable may be set to a list of paths to inform
BLINKER where to find the .LIB files specified in the script file if
they are not in the current directory.
This again might be used to specify a directory used to keep the LIB
files out of the way, or a directory on a RAM disk to improve
performance, or to save repeating the path for each .LIB file to be
linked.
3.5 The CLIPPER variable.
__________________________
The CLIPPER environment variable may be set to a number of parameters
used by Clipper at application run time to control the amount of
memory used for various functions within Clipper, and is fully
documented in the Clipper manual in Chapter 9 "The Run Time
Environment". Please also see section 9.4 of this manual - Set the
Clipper Environment Variable - for more details of the function of
these values.
Proper use of the V and R parameters can greatly increase the amount
of dynamic memory available to a Clipper application linked with
BLINKER.
It should be noted that the CLIPPER environment variable should be
used to disable Expanded / Extended memory usage by Clipper Summer
'87. If this is not done then indexes may be corrupted when Clipper
Summer '87 uses this memory in conjunction with certain Expanded /
Extended memory drivers, or RUN errors may occur. To disable Clipper
Summer '87 usage of Expanded / Extended memory set the CLIPPER
19
Blinker Manual (c) 1990 Blink, Inc.
environment variable to E0 as follows (this may be used in conjunction
with the other settings for number of files etc.):
SET CLIPPER=E0
Alternatively the E0 may be burned into the application using:
BLINKER EXECUTABLE CLIPPER E0
20
Blinker Manual (c) 1990 Blink, Inc.
_________________________________________________________________________
| |
4. Setting up a Link Script File
| |
_________________________________________________________________________
| |
4.1 Overview
_____________
BLINKER, like other linkers, may be invoked from the DOS prompt with a
command line specifying the files and commands required to link an
application. It does not take much of an application, however, to
exceed the DOS command line limit of 128 characters, so when BLINKER
is run it allows the naming of a link script file which contains all
the files and commands, rather than having to type them each time.
The script file may be created with any normal program editor which
stores files in ASCII format. It is usually created with the same file
name as the application to which it refers, and with an extension of
.LNK. Chapter 6 of this manual - BLINKER Script Commands - contains
detailed descriptions of all the commands which may be used either on
the command line or in a script file with BLINKER.
Since BLINKER uses a default extension of .LNK for script files, to
run BLINKER with the commands in a file TEST.LNK simply type the
following at the DOS prompt or in a batch file:
BLINKER @TEST
where TEST.LNK could contain the following lines:
FILE TEST
LIB EXTEND
LIB CLIPPER
Link script files allow you to simply maintain and modify the link
commands required for each application, and are necessary when
creating overlaid applications.
4.2 Reduce the Number of Overlays and Areas
____________________________________________
Blinker automatically manages your overlays, relieving you of the need
to build an overlay structure. All overlayable code can be placed into
either a single internal or a single external overlay. Blinker will
automatically create an internal overlay unless the SECTION INTO
21
Blinker Manual (c) 1990 Blink, Inc.
There is no memory or speed benefit to having multiple overlay areas
i.e. multiple BEGINAREA/ENDAREA commands, multiple SECTIONS (they are
ignored), or multiple external overlays i.e. multiple SECTION INTO
commands. There does appear to be a small speed benefit with external
overlays, but this seems to be very application specific and if the
application is running on a network then very network specific.
Unlike conventional linkers, Blinker maintains a flat overlay
structure allowing any code to call any other code at any time,
regardless of whether or not the code is overlaid or within the same
overlay area.
One of the only reasons to have multiple overlay areas would be in the
relatively unusual case of a conflict between libraries in the script
file, when it may be necessary to order the libraries in such a way
that a non-overlayable library must be placed between overlayable
libraries. Please see the next section for an example of this.
One of the only reasons to have multiple external overlays is that
with a very large application it may be necessary to do so to enable
distribution of the application on 360Kb diskettes.
4.3 Ordering the Libraries
___________________________
Script files are processed in two passes - all the FILE commands
listing the .OBJ files to be linked, and then all the ALLOCATE, LIB
and SEARCH commands, in the order in which they appear in the script
file.
The order of the libraries within the script file is very important,
particularly when multiple libraries contain routines of the same name
and one must be used in preference to the other. The routine which
will be linked into the application is drawn from whichever library
comes first in the script file, which can produce unexpected results
or errors if this is not the routine the application expected.
The library order is also important when libraries refer to each
other, to avoid unresolved externals and the possible additional
overhead of a SEARCH command.
Libraries should be listed within the script file in descending order
of priority. This usually means placing non-overlayable libraries
before the BEGINAREA command, followed by overlayable libraries in the
overlay area between the BEGINAREA and ENDAREA, beginning with your
own libraries, then third party libraries and then EXTEND. CLIPPER and
LLIBCA should be placed in the root at the end of the script file
after the ENDAREA command.
22
Blinker Manual (c) 1990 Blink, Inc.
Remember that anything placed between the BEGINAREA and ENDAREA will
be overlaid, and anything above or below will go into the root.
BLINKER will automatically create an internal overlay unless the
SECTION INTO
file.
Important: BLINKER has no need for any overlay manager files or
libraries, so any references to OVLMGR.OBJ, OVERLAY.OBJ, OVERLAY.LIB
or equivalents should be removed from the script file.
For example:
FILE MAIN # Main routine & code in root for performance
LIB HIGHPRIORITY # Library of highest priority in root
LIB ROOT # Other root libraries
BEGINAREA # Start of overlay area
FILE CLIPCDE1 # Overlayable Clipper .OBJs
FILE CLIPCDE2
ALLOCATE OTHERLIB # Overlayable library
ALLOCATE EXTEND # Overlay EXTEND.LIB
ENDAREA # End of overlay area
SEARCH CLIPPER # CLIPPER.LIB in the root
LIB LLIBCA # C function library in the root
If unresolved externals are displayed at the end of a link then it may
be necessary to change a LIB command to a SEARCH command for the
library in which the external resides. If the name does not come from
any of the 3rd party libraries and is not one of your own then it may
be necessary to SEARCH CLIPPER or EXTEND to resolve the external.
Multiple BEGINAREA and ENDAREAs are usually unnecessary as Blinker
treats code as either overlaid or non-overlaid. Exceptional cases,
such as a user library calling another library which must go in the
root, may require two BEGINAREAs, e.g.
OUTPUT MAIN
23
Blinker Manual (c) 1990 Blink, Inc.
FILE MAIN, FUNCKY # Main routine, dLesko screen driver
LIB FUNBLINK # Root library to allow FUNCKY to be overlaid
BEGINAREA
FILE USER
ALLOCATE USERLIB # Overlayable lib calling functions in XXX
ALLOCATE FUNCKY # In conjunction with FUNBLINK
ENDAREA
LIB XXX # Non-overlayable library replacing functions
BEGINAREA # in EXTEND and which must go in the root
ALLOCATE EXTEND # EXTEND comes after it and is overlaid
ENDAREA
SEARCH CLIPPER # CLIPPER is always in the root
Some libraries require that a special root library be included, e.g
FUNBLINK.LIB for FUNCky. Some also require that a particular .OBJ
remain in the root e.g the FUNCKY.OBJ screen driver from FUNCky and
RESIDENT.OBJ from The Overlay () Library. In many cases only the later
versions of the libraries are overlayable, so please confirm with the
vendor that the version you are using can be overlaid and what they
recommend should go in the root.
When a number of the major 3rd party libraries are being used in the
same application the order we have found to give least problems would
be as follows:
FILE MAIN
FILE FUNCKY # dLesko screen driver
FILE DBUG # HJS research's debugger
FILE RESIDENT # GAMBit OVERCL root module
SEARCH GETIT # Communication Horizons
SEARCH NLEXT87,NL187 or NL287 # Communication Horizons
24
Blinker Manual (c) 1990 Blink, Inc.
LIB FUNBLINK (or SEARCH FUNCKY if no FUNBLINK) # dLesko
LIB PCKERNEL # Genesis Development Corp. root
LIB IDL # IDC
LIB ROOT88 # ProWorks root library
LIB DGE # Bits per Second
LIB SWASYNCH # SilverWare
LIB SWPAINT # SilverWare
LIB CT1 # Nantucket
BEGINAREA
FILE ... # Application OBJs
FILE ... # dGE graphics drivers
ALLOCATE FUNCKY # dLesko overlay
ALLOCATE PCFUNCS # Genesis Development Corp. overlay
ALLOCATE TOOLKIT # Steve Straley
ALLOCATE GRUMPFISH # Grumpfish - various
ALLOCATE FLIP88 # ProWorks overlayable library
ALLOCATE OVERCL # GAMBit
ALLOCATE ARTFUL # ArtFul Applications
LIB SMARTMEM # IDC
ALLOCATE SUPER # Functional Software
ALLOCATE 3PX # 3P Software
ALLOCATE EXTEND # Nantucket
ENDAREA
SEARCH CLIPPER # Nantucket
25
Blinker Manual (c) 1990 Blink, Inc.
LIB TR # Tom Rettig Associates
LIB DCLIP # HJS Research's debugger
LIB LLIBCA # Microsoft
In these examples CLIPPER is being SEARCHed since the majority of the
library is included in each application, so there is no need to
process the cross reference record to save time.
When GETIT or NETLIB are being used GETIT should come first and they
should both come before any other libraries in the script file. They
will also need to be SEARCHed to remove the BLINKER warning message
1005 indicating that they have no cross reference records.
A useful tip for debugging is the difference between a FILE command
and a LIBRARY command. A FILE command defaults to a file extension of
.OBJ and forces the specified file(s) to be included in the .EXE
whether they are used or not. An ALLOCATE, LIBRARY or SEARCH command
defaults to a file extension of .LIB and causes only routines which
are used in the particular application to be included in the .EXE
file.
Both .LIB and .OBJ files may be used with any of these commands, but
the resulting .EXE file size will vary drastically depending on which
command is used. This is because if .LIB files are used with FILE
commands then the whole of the library will be included in the .EXE,
regardless of whether it is needed or not.
The other difference is that if a public symbol such as a procedure or
function name is found to be duplicated in another file in a FILE
command then a warning error message 1004 is issued, whereas if the
file was in an ALLOCATE, LIBRARY or SEARCH command then the duplicate
will be ignored without a message.
This means that a quick way to check libraries for duplicate symbols
in libraries (although the .EXE will probably not run !!) is to
specify all the libraries with extensions in FILE commands rather than
ALLOCATE, LIBRARY or SEARCH commands. As a result, warning messages
will be displayed for all duplicate symbols in the libraries.
26
Blinker Manual (c) 1990 Blink, Inc.
_________________________________________________________________________
| |
5. Understanding Overlays
| |
_________________________________________________________________________
| |
5.1 Overview
_____________
Once an application program has become larger than 500KB it becomes
necessary to introduce overlaying to the application. Overlaying
allows mutually exclusive pieces of the program to be loaded in the
same area of memory at run time, depending on which piece of the
program is required at any point in time. These pieces are known as
overlays.
Most existing applications set up to link with PLINK86plus will link
with BLINKER without making many changes to the PLINK86plus script
file, although the full advantages of BLINKER will not be apparent.
BLINKER provides the immediate improvements of linking many times
faster than with PLINK86plus and implementing dynamic overlaying of
Clipper routines.
However, some large or complicated applications, and also those
involving overlaying of C and Assembler, may require modification to
the script file before they will link successfully.
In all cases the major benefits of BLINKER will not be realized until
some restructuring of the application is performed. Nevertheless, the
benefits of these changes will vastly outweigh the time spent in
restructuring the application.
The following sections should be studied in detail in order to fully
realize the benefits offered by BLINKER to the Clipper programmer.
5.2 Traditional Overlays - PLINK86plus
_______________________________________
An application consists of one or more PRG files compiled using
Clipper and then linked together using one of a number of commercially
available linkers.
With traditional, or static, overlaying techniques the application
programmer must determine which parts of the program are mutually
exclusive and must then pass this information via a script file to the
overlay linker such as PLINK86plus or .RTLINK.
Each overlay consists of one or more OBJ files, thus the smallest
overlay unit with traditional techniques is one OBJ file. Overlays may
27
Blinker Manual (c) 1990 Blink, Inc.
be grouped into areas or nested within one another which further
complicates the overlay structure.
An application EXE file using PLINK86plus overlays comprises, in the
following order:
1. All the OBJ files which are to remain in memory the whole
time.
2. Spaces reserved for the sets of mutually exclusive OBJ files
to be overlaid.
3. The overlay manager.
4. Any parts of the .LIB library files required for the
application.
The EXE file is loaded into memory exactly as it is stored on disk,
and the remaining memory above the library code is made available to
the application to use as it wishes. Clipper divides this memory up on
a proportional basis for various functions such as memory variable
space, dynamic memory for temporary work areas, index buffers and
memory to run DOS commands. See section 9.4 Set the CLIPPER
Environment Variable for details of how this memory is allocated.
Let us consider the following simple script file for an application
using PLINK86plus overlays (the size of each OBJ file is shown in
brackets to clarify the memory layout diagram).
FILE MAIN (10KB)
OUTPUT MAIN
BEGINAREA
SECTION FILE SETUP (20KB)
SECTION FILE CUSTOMER (20KB)
SECTION FILE REPORTS (30KB)
BEGINAREA
SECTION FILE REPORT1 (10KB)
SECTION FILE REPORT2 (30KB)
SECTION FILE REPORT3 (15KB)
28
Blinker Manual (c) 1990 Blink, Inc.
ENDAREA
SECTION FILE UTILITIES (10KB)
ENDAREA
FILE PROCS (30KB)
LIB EXTEND
LIB CLIPPER
LIB OVERLAY
MAIN.OBJ is the main menu with four choices, and depending on which
choice is made either SETUP.OBJ, CUSTOMER.OBJ, REPORTS.OBJ or
UTILITIES.OBJ will be loaded into the overlay area reserved for them.
These files must be mutually exclusive, i.e. never call each other, as
they will be loaded into the same AREA of memory at run time. Problems
arising from allowing two SECTIONS of the same overlay AREA to call
one another produce erratic results and are difficult to isolate.
Careful thought is therefore necessary when designing an overlay
structure.
Each overlay AREA is large enough to contain the largest combination
of any given SECTION plus the largest SECTION in any nested AREA
dependent on that SECTION. This space is reserved in the EXE file and
in memory when the EXE file is loaded, so is never available to
Clipper for its free pool.
The size of the inner overlay AREA would therefore be 30KB since
REPORT2 is the largest of the three report overlays and the size of
the outer AREA would be 60KB since the report SECTION is the largest
and is made up of 30KB from REPORTS and 30KB from the inner overlay
AREA.
File PROCS is in the root because it contains procedures used by all
the other files.
Routines required by the OBJ files are extracted from the libraries
specified and placed in the root along with MAIN and PROCS. Typically
the overhead from CLIPPER.LIB and EXTEND.LIB is around 160 kb for
code, plus about 80 to 100 kb for data and workareas at run time.
A diagram showing the structure of this EXE file using PLINK86plus
overlays once it is loaded in memory is shown over the page. It is
assumed that DOS and TSRs take up about 100KB, so this application is
29
Blinker Manual (c) 1990 Blink, Inc.
not low on memory but is used to illustrate the way that memory is
used.
30
Blinker Manual (c) 1990 Blink, Inc.
640Kb +--------------------------------------------+
| |
| Free Pool (180) |
| |
460 KB +--------------------------------------------|
| CLIPPER Work Areas (100) |
360 KB +--------------------------------------------|
| REPORT1 (10) |
| REPORT2 (30) |
| REPORT3 (15) |
330 KB +--------------------------------------------|
| SETUP (20) |
| CUSTOMER (20) |
| REPORTS (30) |
| UTILITIES (10) |
300 KB +--------------------------------------------|
| CLIPPER + EXTEND (160) |
140 KB +--------------------------------------------|
| PROCS (30) |
110 KB +--------------------------------------------|
| MAIN (10) |
100 KB +--------------------------------------------|
| DOS, TSRs etc. (100) |
000 KB +--------------------------------------------|
Structure of application overlaid with PLINK86plus.
When any procedure in SETUP is called the whole of the SETUP file is
loaded into the overlay area from disk and execution continues. SETUP
will remain in the overlay area until any procedure in one of the
other files CUSTOMER, REPORTS or UTILITIES is called. Then the whole
of the requested file is loaded into the overlay area, overwriting
SETUP.
The linker calculates the largest overlay for each area and reserves
enough space in the EXE file for it, which may waste a significant
amount of memory if one of the overlays is larger than the others. At
run time, when a particular overlay is called the overlay manager
loads the required overlay into the reserved space in memory. Any
previous overlays in that area are overwritten and control is
transferred to the new overlay.
With a large application the creation of an overlay structure can be a
time-consuming and complicated process in itself, as too much may
depend on the choices made by the operator at run time. The more
flexible an application must be to use, the more difficult it can be
to specify an overlay structure for it that will both work and fit in
the available memory.
31
Blinker Manual (c) 1990 Blink, Inc.
Often even minor changes in an application can require complete
reorganization of the overlay structure.
5.3 Dynamic Overlays - BLINKER
_______________________________
Dynamic overlays remove the need for an overlay structure. Each unit
of code which may be overlaid is treated as if it has the potential to
call any of the other overlay units. An area of memory is put aside
for these overlays, and each time the application program is run the
manager loads the overlay units into this area in the order in which
they are called.
The manager maintains a table of the overlays and their location in
the overlay area, along with information on whether each overlay is
currently in use, how often it has been used and when it was last
used. Once the overlay area is fully utilized, overlays are discarded
according to their frequency and history of usage to make room for new
overlays. This process is known as dynamic overlaying because the
loading and discarding of overlays varies each time the application is
run.
The process of loading and executing an overlay involves the overlay
manager in three stages which are as follows:
1. Finding the overlay code in the overlay file and loading the code
into the appropriate place in the overlay area.
2. Linking or fixing up any references made by the code to external
variables and procedures, i.e. those outside of the overlay code
itself. It does this from a table of external references stored within
the overlay code, in much the same way as DOS fixes up references to
specific segments within an EXE file when it loads the EXE file at run
time.
3. Transferring control to the newly loaded overlay in such a way
that the manager will regain control once the overlay has finished
execution.
BLINKER allows the developer to dynamically overlay program code for
optimum use of dynamic memory without the complexity of overlay
structures. It does so by dividing the code into two classes - code
which may be overlaid and code which must remain in memory the whole
time. All overlay structures for the code to be overlaid are ignored,
and the structure commands are used purely to differentiate the code
which must remain in the root from the code to be overlaid.
32
Blinker Manual (c) 1990 Blink, Inc.
With BLINKER the root structure remains the same as with PLINK86plus,
but no space for overlays is reserved in the EXE file. The space is
allocated dynamically at run time by the overlay manager from
Clipper's dynamic memory pool, as and when required.
BLINKER manages Clipper overlays at the procedure or function level,
rather than at the OBJ file level used with static overlays, which
allows much more efficient use of memory and much faster loading of
overlays when they are required.
All nested BEGINAREAs are therefore ignored by BLINKER, since any
procedure may call any other procedure at any time, regardless of
whether one or other of the procedures is overlaid or not. The
previous script file would therefore be treated by BLINKER as if it
contained the following:
FILE MAIN (10KB)
OUTPUT MAIN
BEGINAREA
FILE SETUP (20KB)
FILE CUSTOMER (20KB)
FILE REPORTS (30KB)
FILE REPORT1 (10KB)
FILE REPORT2 (30KB)
FILE REPORT3 (15KB)
FILE UTILITIES (10KB)
ENDAREA
FILE PROCS (30KB)
LIB EXTEND
LIB CLIPPER
A diagram showing the structure of this EXE file using BLINKER
overlays once it is loaded in memory is shown below.
33
Blinker Manual (c) 1990 Blink, Inc.
640Kb +--------------------------------------------+
| |
| Free Pool (235) |
| |
405 KB +--------------------------------------------|
| CLIPPER Work Areas (100) |
305 KB +--------------------------------------------|
| Overlay Manager (5) |
300 KB +--------------------------------------------|
| CLIPPER + EXTEND (160) |
140 KB +--------------------------------------------|
| PROCS (30) |
110 KB +--------------------------------------------|
| MAIN (10) |
100 KB +--------------------------------------------|
| DOS, TSRs etc. (100) |
000 KB +--------------------------------------------|
Structure of application overlaid with BLINKER.
As can be seen, 55KB has immediately been made available to the
Clipper free pool, and with appropriate calls to the BLIOVLCLR ()
function (for further details see Chapter 7, BLINKER Programming
Functions) this saving can be maintained throughout execution of the
application.
The overlaying on a procedure or function basis by BLINKER also means
that all the procedures for all the overlays may be placed in one .OBJ
file for convenience, once the necessary changes are made in the
Clipper script files. This will have the added benefit of creating
only one symbol table, which greatly reduces the memory requirements
for the EXE file symbol table.
The developer may set, either at link time or at run time, an
operating size for the pool of memory BLINKER uses to manage its
overlays. This operating pool size defaults to 40KB unless overridden.
For details on how this operating size may be changed and will affect
performance see Chapter 9, Getting More Out of BLINKER.
Each time an overlaid procedure is called, BLINKER checks to see if it
has used as much memory as specified in the operating pool size. If it
has not reached the operating pool size then memory is allocated from
Clipper's dynamic pool for the procedure, the procedure is loaded and
then executed.
If, however, the pool size has been reached, BLINKER will attempt to
discard any inactive overlays from the pool in order to free up space
for the new overlay. BLINKER checks for the most suitable overlay or
34
Blinker Manual (c) 1990 Blink, Inc.
overlays based on how recently the overlay was used and how often it
has been used. Provided enough memory has been freed, the overlay is
loaded and execution continues.
If there is still not enough memory once all the inactive overlays
have been discarded, then BLINKER will allocate more memory from
Clipper's free pool anyway, and will increase the size of the overlay
pool by the required amount.
BLINKER automatically links in the overlay manager to the application,
performing the linking process significantly faster than conventional
linkers.
Clipper creates a symbol table in every OBJ file with 16 bytes for
each symbol or name in the file. This table is directly copied into
the memory resident part of the EXE file at link time, with no removal
of duplicate entries.
Since BLINKER manages the Clipper overlays at the procedure level, the
programmer may combine multiple source files into one OBJ file at
compilation time, allowing Clipper to remove these duplicates entries
automatically, which can save many KB in the EXE file and at run time.
Clipper imposes a limit of 243 procedures in a single OBJ file.
At application run time, if a Clipper overlay is not loaded the
BLINKER overlay manager will dynamically allocate enough memory for
the procedure or function. This will continue until the size of the
overlay pool has reached a limit defined by the developer. At that
point the BLINKER overlay manager will attempt to re-use overlay areas
which are no longer in use, based on factors such as usage count and
age of the overlay.
If all the areas are in use then the manager will request more memory
from Clipper and raise the overlay pool limit to the new value. A
function BLIOVLCLR () is also provided for the developer to request
that the overlay manager free all unused overlay memory at any time,
thus making it available to the application. No other linker can
currently offer this flexibility.
5.4 Choosing what to overlay
_____________________________
ALL OBJs and LIBRARies of Clipper compiled code can be dynamically
overlaid using the FILE and ALLOCATE command respectively within the
BEGINAREA / ENDAREA commands.
The FILE command is used to list .OBJ files that MUST be linked in to
an application.
35
Blinker Manual (c) 1990 Blink, Inc.
The ALLOCATE command is a command from PLINK86plus that is not
supported in the version of PLINK86plus supplied with Clipper Summer
'87. It is used in the overlay area to instruct BLINKER to only
include the .OBJ files from that library that are actually required by
the application being linked, in the same way as a LIBRARY command.
The difference between an ALLOCATE command used between the BEGINAREA
/ ENDAREA commands and a LIBRARY command used in the root is that the
included .OBJ files are dynamically overlaid at run time rather than
being placed in the root with the LIBRARY command.
The ALLOCATE command allows the developer to create libraries of his
own standard routines which can be linked with every application but
only the required .OBJ files will be included in the final .EXE file.
Additionally, the code included will be dynamically overlaid as and
when required rather than taking up memory in the root, provided the
ALLOCATE is between the BEGINAREA and ENDAREA commands.
EXTEND.LIB may be overlaid using the ALLOCATE command in the same way
as pure Clipper compiled code, since it is made up of WELL BEHAVED C
and Assembler code.
Overlaying of CLIPPER.LIB is NOT supported in this version of BLINKER.
In practice, there is no real benefit to doing so, since the majority
of the routines in it are called so often that the overlay swapping
algorithm would cause them to remain in memory the whole time anyway.
Other C and Assembler code may be dynamically overlaid in the same way
as Clipper compiled code PROVIDED it is not by its very nature
impossible to overlay.
For example, routines to handle interrupts CANNOT be overlaid in any
way as there is no guarantee that they will be resident in memory when
the interrupt occurs. This type of code MUST be placed in the root.
Code to be overlaid should not modify or store data in segments that
are of class CODE as these are the segments which are overlaid, and
overlaid code is not saved, it is merely discarded and reloaded as
required. It is possible to store temporary data in the CODE segment,
but it should be remembered that between one call to the procedure and
the next it may have been swapped out and reloaded, which would mean
that the modified data would be lost.
Code to be overlaid should be CALLed and RETurned from rather than
using jumps, since the overlay manager needs to track which overlays
are loaded and which are in use in order to determine which to swap
out.
36
Blinker Manual (c) 1990 Blink, Inc.
Code passing pointers to other code which are only evaluated at run
time cannot be overlaid because it cannot be assumed that a piece of
code will be in the same place on any two calls to the code. This can
rule out jump tables set up at run time, although jump tables which
may be evaluated at link time are overlayable.
The majority of C code is overlayable by these definitions, but
Assembler code can often contain constructs which will prevent
overlaying.
Whether a particular C or Assembler routine may be overlaid can only
be established by trying it under CAREFULLY MONITORED circumstances to
ensure that it is functioning correctly.
Blink Inc. has been and is currently working closely with the
developers of all the major third party libraries to enable them to
dynamically overlay as much of their code as is is possible, and to
make this as easy as possible for the Clipper developer. A chart of
the current compatibility of various commercial libraries is supplied
on the distribution disk in the file 3RDPARTY. If you would like the
most up to date list it can be downloaded from our Technical Support
BBS (804) 355-1111.
Feel free to experiment under CAREFULLY MONITORED circumstances, but
Blink, Inc. cannot guarantee that any particular piece of C or
Assembler code can be overlaid, or be held responsible for the
consequences.
37
Blinker Manual (c) 1990 Blink, Inc.
_________________________________________________________________________
| |
6. BLINKER Script Commands
| |
_________________________________________________________________________
| |
6.1 Overview
_____________
This section is intended as a reference for all the BLINKER script
file commands, but a thorough understanding of these commands should
be obtained before attempting to create an application or to convert
an existing application for use with BLINKER.
BLINKER is driven by a script file containing commands which are
compatible with the PLINK86plus commands documented in the Clipper
manual. For existing applications using overlays of pure Clipper
compiled code, with no other languages involved such as C and
Assembler, the existing PLINK86plus script file may be used with a few
minor changes.
For more information on the use of script files and overlays with
Clipper and linkers please refer to the chapter in the Clipper Manual
entitled Compiling and Linking.
It should be noted that each BLINKER command which is compatible with
PLINK86plus requires exact conformity with the PLINK86plus format for
that command.
Script file(s) are specified on the command line and default to an
extension of .LNK. They cannot be nested, but more than one may be
used on the command line, along with single PLINK86plus commands,
e.g.:
BLINKER @DEFAULTS @OTHER LIB EXTEND VERBOSE
This command line instructs BLINKER to read the script file
DEFAULTS.LNK followed by the script file OTHER.LNK. It also instructs
BLINKER to use the library EXTEND.LIB and to display a VERBOSE listing
of the .OBJ files being processed.
The full names of the commands or any unique abbreviation thereof may
be used in the script file, although it is recommended that at least
four letters be used for clarity.
The only non-standard PLINK86plus command is the BLINKER command,
which is provided to handle all the extra features BLINKER provides
which have no counterparts in PLINK86plus. All the BLINKER commands
must therefore be prefixed with BLINKER or an abbreviation thereof to
indicate that they are not PLINK86plus compatible.
38
Blinker Manual (c) 1990 Blink, Inc.
A table of all the BLINKER and PLINK86plus commands in alphabetical
order appears below for quick reference, followed by a section on each
command containing a description of each one and how it is used. The
table shows which of the PLINK86plus commands BLINKER will process and
which commands it will ignore.
6.2 Command Actions Table
__________________________
Command BLINKER Action
# Processed (comment).
ALLOCATE Processed.
BATCH Processed (default).
BEGINAREA Processed.
BLINKER Processed.
DEBUG Processed.
ENDAREA Processed.
FILE Processed.
HEIGHT Ignored.
LIBRARY Processed.
LOWERCASE Ignored.
MAP Processed.
MIXCASE Ignored.
MODULE Ignored.
NOBELL Processed.
OUTPUT Processed.
OVERLAY Ignored.
SEARCH Processed.
SECTION Processed.
39
Blinker Manual (c) 1990 Blink, Inc.
STACK Processed.
UPPERCASE Processed (default).
VERBOSE Processed.
WIDTH Ignored.
WORKFILE Ignored.
6.3 # (comment)
________________
- Comment line
Syntax: # ...
All lines beginning with a # sign in the script file are treated as
comment lines and are ignored by BLINKER.
6.4 ALLOCATE
_____________
- Specify one or more libraries to insert
Syntax: ALLOCATE
The ALLOCATE command is used between a BEGINAREA and ENDAREA to
instruct BLINKER to only include and overlay the .OBJ files from the
named libraries that are actually required by the application.
This command allows the developer to create libraries of his own
standard routines, using a library manager such as Microsoft LIB.EXE.
These libraries can be linked with every application, but only the
required .OBJ files will be included in the final .EXE file, and will
be dynamically overlaid as and when required, rather than taking up
memory in the root.
Since the overlay structure is ignored, to ensure that all the .OBJ
files required can be found the ALLOCATE commands should be the last
commands in the last overlay area.
All libraries of Clipper compiled code may be overlaid using the
ALLOCATE command, as may libraries of "well behaved" C and ASM code
such as EXTEND.LIB. See also the file 3RDPARTY on the distribution
diskette and section 5.4 Choosing What To Overlay.
40
Blinker Manual (c) 1990 Blink, Inc.
6.5 BATCH
__________
- Specify to the linker it is running in batch mode
Syntax: BATCH
The BATCH command is used to specify to the linker that it is being
run in batch mode. If a particular file or library cannot be found in
the appropriate path then linking terminates with an error, rather
than the default which is to prompt the operator for an alternative
path where the file or library may be found.
BLINKER ignores the BATCH command as it is the default mode of
operation for BLINKER.
6.6 BEGINAREA
______________
- Specify start of a dynamic overlay area
Syntax: BEGINAREA
The BEGINAREA command is used to specify to the linker the start of an
overlay area in the output file. Each BEGINAREA should have a
corresponding ENDAREA to indicate the end of the overlay area.
With static overlays BEGINAREAs, and therefore overlay areas, may be
nested within one another so long as there is a corresponding ENDAREA
for each BEGINAREA. This allows the developer to create a structure of
overlays within an area to use the minimum amount of memory for the
maximum number of overlay routines.
With BLINKER dynamic overlays the mutual dependency of each overlay
procedure or file is unimportant, as is the nesting structure of the
areas, so there is no need for multiple BEGINAREA / ENDAREAs. The
BEGINAREA and ENDAREA commands are simply treated as being markers of
the beginning and end of procedures and files which may be overlaid.
All Clipper .OBJ files listed between a BEGINAREA and ENDAREA are
overlaid on a procedure or function basis, no matter how many
procedures or functions are present in the file. For this reason,
large memory savings can be made by including many functions and
procedures into each Clipper.OBJ file using .CLP files (see the
Clipper manual).
All non-Clipper .OBJ files listed between a BEGINAREA and ENDAREA are
overlaid on a segment basis, i.e. the whole CODE segment for each OBJ
is loaded into memory whenever any function or procedure within that
41
Blinker Manual (c) 1990 Blink, Inc.
.OBJ file is called. For more details on how functions and procedures
may be kept in separate segments to reduce the overlay unit size
please refer to the appropriate compiler manual for the language being
used.
6.7 BLINKER DEBUG HANDLE
_________________________
- Specify output file handle for debugging routines
Syntax: BLINKER DEBUG HANDLE
This BLINKER command is used to set the default output file handle for
the debugging routines in the BLINKER overlay manager. These debugging
routines are enabled by placing the DEBUG command somewhere in the
script file. The debugging routines include a display of the status of
all the overlay procedures in the overlay pool and a trace of
procedure calls to reach the current procedure. They are detailed in
Chapter 7, BLINKER Programming Functions.
The handle number can be set to either 1 (the default) to send output
to the screen, 2 to send output to the standard error device or 4 to
send output to the printer.
For example, to set the default output handle to the printer use the
following:
BLINKER DEBUG HANDLE 4
6.8 BLINKER DEMONSTRATION CALLS
________________________________
- Specify number of calls for demonstration version
Syntax: BLINKER DEMONSTRATION CALLS
This BLINKER command is used to set a limit on the number of overlay
procedures which may be called before ending the application with the
demonstration procedure limit exceeded message. It may be set to any
number from 1 to 65535.
This could be used to create a demonstration version of the
application without having to modify the application - see also
Chapter 8, Creating Demonstration Versions.
If the calls limit is set, when it is reached the error handling
procedure BLERRPRG is called with error number 1207 indicating that
the demonstration call limit has been exceeded.
42
Blinker Manual (c) 1990 Blink, Inc.
For example, to set the application to a limit of 100 procedure calls
use the following:
BLINKER DEMONSTRATION CALLS 100
Note: the demonstration restrictions are only checked when overlays
are loaded, so to use them please ensure that at least one function or
procedure which is called regularly is overlaid.
6.9 BLINKER DEMONSTRATION DATE
_______________________________
- Specify expiration date for demonstration version
Syntax: BLINKER DEMONSTRATION DATE
This BLINKER command is used to set the expiration date of an
application, after which the application will end with the
demonstration date limit exceeded message. It is set in the format
mm/dd/yy.
This could be used to create a demonstration version of the
application without having to modify the application. See also Chapter
8, Creating Demonstration Versions.
If the date limit is set and when an application loads its first
overlay the system date is after the expiration date, the error
handling procedure BLERRPRG is called with error number 1208
indicating that the demonstration date limit has been exceeded.
For example, to set the application expiration date to the last day of
1990 use the following:
BLINKER DEMONSTRATION DATE 12/31/90
Note: the demonstration restrictions are only checked when overlays
are loaded, so to use them please ensure that at least one function or
procedure which is called regularly is overlaid.
6.10 BLINKER DEMONSTRATION MINUTES
__________________________________
- Specify number of minutes for demonstration version
Syntax: BLINKER DEMONSTRATION MINUTES
This BLINKER command is used to set the number of minutes which an
application may run before ending the application with the
43
Blinker Manual (c) 1990 Blink, Inc.
demonstration minutes limit exceeded message. It may be set from 1
minute to 65535 minutes.
This could be used to create a demonstration version of the
application without having to modify the application. See also Chapter
8, Creating Demonstration Versions.
If the time limit is set then when it is reached the error handling
procedure BLERRPRG is called with error number 1209 indicating that
the demonstration minutes limit has been exceeded.
For example, to set the application to a limit of 10 minutes of
execution use the following:
BLINKER DEMONSTRATION MINUTES 10
Note: the demonstration restrictions are only checked when overlays
are loaded, so to use them please ensure that at least one function or
procedure which is called regularly is overlaid.
6.11 BLINKER ENVIRONMENT NAME
_____________________________
- Specify environment name for BLINKER parameters
Syntax: BLINKER ENVIRONMENT NAME
At application run time the BLINKER overlay manager checks the DOS
environment for the BLINKER environment variable, and if this is
present then the variable is examined for certain run time parameters
to the overlay manager.
This BLINKER command is used to set the environment name checked to a
different name to BLINKER. For example, to set the variable name to
TESTAPP use the following command:
BLINKER ENVIRONMENT NAME TESTAPP
At run time, the BLINKER overlay manager will now check the
environment for the TESTAPP variable, and if it is present then the
variable will be checked for the following parameters:
/DHn (Debug handle)
/OOnnn (Overlay pool Operating size in KB)
The /DHn parameter is an override of the link time BLINKER command
BLINKER DEBUG HANDLE n which controls the handle of the destination of
44
Blinker Manual (c) 1990 Blink, Inc.
debug output from BLINKER. For details of the usage of this value see
section 6.7 BLINKER DEBUG HANDLE.
The /OOnnn parameter is an override of the link time BLINKER command
BLINKER OVERLAY OPSIZE n which controls the operating size of the
BLINKER overlay pool. For details of the usage of this value see
section 6.22 BLINKER OVERLAY OPSIZE.
For example, to set the overlay pool operating size of the above
application to 30 KB, use the following command at the DOS prompt:
SET TESTAPP=/OO30
This parameter is used to vary the operating size at application run
time without having to relink the application.
6.12 BLINKER ENVIRONMENT OVERRIDE
_________________________________
- Specify environment settings may override defaults
Syntax: BLINKER ENVIRONMENT OVERRIDE
As a default the variables set using the BLINKER EXECUTABLE CLIPPER
command may not be overridden at application run time. This allows
multiple applications with different requirements to run on the same
machine without changing the CLIPPER environment settings.
This BLINKER command is used to tell BLINKER to allow the Clipper
environment variables set using the BLINKER EXECUTABLE CLIPPER command
to be overridden at application run time by the settings of the
CLIPPER environment variable.
6.13 BLINKER EXECUTABLE CLIPPER
_______________________________
- Specify default CLIPPER environment settings
Syntax: BLINKER EXECUTABLE CLIPPER
This BLINKER command is used to burn default values for the Clipper
run time environment variables into the executable file. These burnt
in values cannot be overridden at run time, unless the BLINKER
ENVIRONMENT OVERRIDE is specified. Use of this command ensures that
the application will run however the environment on the destination
machine has been set up.
45
Blinker Manual (c) 1990 Blink, Inc.
Note: The values detailed here are applicable to Clipper Summer '87,
please refer to the Clipper 5.0 manual to check which ones are
applicable to 5.0
The Clipper run time parameters are detailed in Chapter 9 - The Run
Time Environment - of the Clipper Summer '87 manual, and in section
9.4 - Set the Clipper Environment Variable - of this manual. They
consist of 6 values:
Ennn Expanded memory (KB)
Fnnn Number of files
Rnnn Run command memory (KB)
Sn Snow indicator
Vnnn Variable memory (KB)
Xnnn eXclude memory (KB)
These values can be set using the BLINKER EXECUTABLE CLIPPER command
using the same format as the SET CLIPPER environment command in DOS.
Only those parameters set using the BLINKER EXECUTABLE CLIPPER command
cannot be overridden at application run time (unless BLINKER
ENVIRONMENT OVERRIDE was specified), the rest will have the same
defaults as before which may be set from the environment in the normal
way.
For example, to ensure that 41 files are available to Clipper and that
100 Kb will be available to run external commands use the following
command:
BLINKER EXECUTABLE CLIPPER F41;R100
At run time, the F and R parameters in the CLIPPER environment will be
ignored, but all the other parameters will be used in the normal way.
It should be noted that the CLIPPER environment variable should be
used to disable Expanded / Extended memory usage by Clipper Summer
'87. If this is not done then indexes may be corrupted when Clipper
Summer '87 uses this memory in conjunction with certain Expanded /
Extended memory drivers, or RUN errors may occur. To disable Clipper
Summer '87 usage of Expanded / Extended memory set the CLIPPER
environment variable to E0 as follows (this may be used in conjunction
with the other settings for number of files etc.):
46
Blinker Manual (c) 1990 Blink, Inc.
SET CLIPPER=E0
Alternatively the E0 may be burned into the application using:
BLINKER EXECUTABLE CLIPPER E0
6.14 BLINKER EXECUTABLE SERIAL
______________________________
- Specify serial number to encrypt into the .EXE
Syntax: BLINKER EXECUTABLE SERIAL
This BLINKER command is used to encrypt a serial number and other
information of up to 50 characters into the executable file which can
then be examined by the application using the BLISERNUM () function at
run time.
This information is encrypted into the executable file and could be
used to hide a serial number and licensee name in the executable file
as a form of copy protection.
Any information following the BLINKER EXECUTABLE SERIAL command on the
same line of the script file is encrypted into the .EXE file up to a
limit of 50 characters. An identical string is returned in the same
format by the BLISERNUM () function at run time.
For example, to encrypt a payroll application with a serial number of
00100001, a 5 user license and a licensee name of Blink, Inc. use the
following command:
BLINKER EXECUTABLE SERIAL 00100001 5 Blink, Inc.
At application run time these values can be examined by assigning the
serial number to a string and then manipulating it using SUBSTR, for
example:
TMPSTRVAR = BLISERNUM ()
? "Serial number :", SUBSTR(TMPSTRVAR,1,8)
? "Number of users :", VAL(SUBSTR(TMPSTRVAR,10,1))
? "Licensed to :", SUBSTR(TMPSTRVAR,12,20)
6.15 BLINKER INCREMENTAL FILE
_____________________________
47
Blinker Manual (c) 1990 Blink, Inc.
- Specify alternate file name for incremental file
Syntax: BLINKER INCREMENTAL FILE
This BLINKER command is used to specify an alternative name for the
incremental link file for this application. The default name used is
the same as the .EXE file to be output, and the default extension used
is .BIF. Please ensure that the file named does not already exist as
an incremental file for a different application.
For example, to ensure that the .BIF file is created on the RAM drive
E: and has a name of TEMP.BIF, use the following command:
BLINKER INCREMENTAL FILE E:TEMP.BIF
6.16 BLINKER INCREMENTAL OFF
____________________________
- Disable incremental linking mode
Syntax: BLINKER INCREMENTAL OFF
This BLINKER command is used to turn off BLINKER's use of incremental
linking, so every link performed will be a full one, no incremental
.BIF file will be created, and no padding will be left between each
procedure to allow room for incremental linking.
This command should be used for the final link of an application to
obtain its smallest memory requirement.
6.17 BLINKER INCREMENTAL PAD
____________________________
- Specify size of padding for incremental linking
Syntax: BLINKER INCREMENTAL PAD
This BLINKER command is used to set the size of the padding attached
to the end of each procedure when it is first linked incrementally.
The parameter is a decimal number indicating the size in bytes to be
added at the end of each procedure to leave room for expansion, and
may be any size up to 65535. (The default value is 128, which should
leave a reasonable amount of padding for the majority of simple
changes made during final development of a routine)
Increasing this value means that the application would link
incrementally more often without having to do a full link, but it may
48
Blinker Manual (c) 1990 Blink, Inc.
mean that the overhead of padding in the root would cause the
application to run out of memory.
For example, to leave 200 bytes at the end of each procedure to allow
for expansion, add the following line to the link script file:
BLINKER INCREMENTAL PAD 200
6.18 BLINKER MEMORY PACK
________________________
- Specify automatic memory packing frequency
Syntax: BLINKER MEMORY PACK
This BLINKER command is used to set the frequency with which the
BLINKER overlay manager defragments Clipper free memory. The parameter
is a decimal number indicating the number of procedure calls after
which memory is defragmented, and may be any value from 0 to 65534.
(The default value is 0, which causes no packing to occur)
Note: This feature is only supported with Clipper Summer '87.
Clipper is continually allocating and freeing dynamic memory causing
it to become more and more fragmented as execution of an application
continues. Clipper only considers memory to be available if it is in
chunks of 4KB or greater, thus large applications can often run out of
memory after prolonged execution.
The BLINKER MEMORY PACK command allows the developer of an application
to defragment dynamic memory as often as needed without modifying the
application, and to tune the frequency of the packing to suit the
individual application.
The defragmentation consists of two things, joining up of contiguous
free blocks of memory and then resetting the roving pointer used for
the next memory allocation to point to the lowest available location
in memory. This causes memory to be allocated from the beginning each
time rather than fragmenting the whole of memory, which can
significantly reduce the deterioration of available memory due to
fragmentation.
Due to the underlying architecture of Clipper Summer '87's memory
allocation it is not possible to move allocated blocks of memory
around, as there is no means of updating the pointer(s) to allocated
blocks. This means that true garbage collection is impossible, but the
defragmentation described here is the next best thing and still helps
the problem considerably.
49
Blinker Manual (c) 1990 Blink, Inc.
Setting the frequency to a low number may slow down the application
but will keep memory fragmentation to a minimum, giving the maximum
saving on memory.
Setting the frequency to a higher number will not noticeably slow the
application down, but the memory gain will be less as the
fragmentation will be relatively worse (although still a lot better
than with no packing at all.)
An optimum frequency appears to be around 10 for an average
application, giving a significant increase in memory while not
significantly slowing the application.
The optimum frequency for a given application may vary considerably
from this frequency, and can only be established by a bit of trial and
error.
For example, to set the pack frequency for the application being
linked to once every 20 procedure calls use the following:
BLINKER MEMORY PACK 20
6.19 BLINKER MESSAGE NOBLINK
____________________________
- Disable blinking of eyes during linking
Syntax: BLINKER MESSAGE NOBLINK
This BLINKER command is used to switch off the blinking eyes which are
displayed while BLINKER is running.
6.20 BLINKER MESSAGE NOWARNING
______________________________
- Disable display of link time warning messages
Syntax: BLINKER MESSAGE NOWARNING
This BLINKER command is used to suppress the display of BLINKER
warning messages 1001 to 1006.
6.21 BLINKER MESSAGE WINK
_________________________
- Enable single eye winking during linking
Syntax: BLINKER MESSAGE WINK
50
Blinker Manual (c) 1990 Blink, Inc.
This BLINKER command is used to enable the winking of only one eye
while BLINKER is running.
6.22 BLINKER OVERLAY OPSIZE
___________________________
- Specify default overlay pool operating size
Syntax: BLINKER OVERLAY OPSIZE
This BLINKER command is used to set the operating size of the dynamic
overlay pool at run time in KB, and may be any value from 1 to 500KB.
The default operating size is 40KB but this may be made smaller to
save memory or larger to reduce the number of disk accesses made by
the overlay manager to re-load overlaid procedures.
For a complete discussion of how the operating size is used at run
time see section 5.3 Dynamic Overlays - BLINKER.
For example, to set the overlay pool size for the application being
linked to 20KB use the following:
BLINKER OVERLAY OPSIZE 20
To determine the minimum setting for the OPSIZE, set it to a small
value such as 10 KB, run through all the options of the application
WITHOUT performing a BLIOVLCLR () and then check the value of the
BLINKER function BLIOVLOPS () just before quitting the application and
returning to DOS. The value returned by the BLIOVLOPS () function will
be the minimum value for the OPSIZE.
6.23 BLINKER PROCEDURE DEPTH
____________________________
- Specify maximum depth of procedure nesting
Syntax: BLINKER PROCEDURE DEPTH
This BLINKER command is used to indicate to BLINKER the maximum depth
of nesting of overlaid procedures which will occur in the application
at run time. This depth is the number of procedure calls that have
been executed without a procedure ending, for example if procedure A
calls procedure B which calls procedure C then the maximum depth is 3,
but if procedure B returns to procedure A, which then calls procedure
C then the maximum depth is 2.
51
Blinker Manual (c) 1990 Blink, Inc.
The default depth is 20 procedures, but this may be increased if it is
possible for more nesting to occur, e.g. if a recursive procedure (one
that calls itself) is used, it is likely that more depth will be
needed. The overhead is approximately 1KB per 10 levels, thus the
default of 20 procedures has an overhead of approximately 2KB, and
this will rise proportionally as the PROCEDURE DEPTH is increased.
With most applications the only time that it should be necessary to
use this command is if an application terminated with error 1206:
maximum procedure nesting depth exceeded. The value should be
increased in increments of 5 or 10 until the error message is not
received.
BLINKER can only check the stack when executing overlaid code.
However, some applications making use of third party libraries linked
into the root, especially in a network environment, may require an
increase in the PROCEDURE DEPTH. Symptoms indicating this include
erratic hanging of the machine, spurious characters on the screen and
other fatal errors which do not happen regularly.
For example, to set the maximum nesting level of the application being
linked to 50 levels use the following:
BLINKER PROCEDURE DEPTH 50
6.24 DEBUG
__________
- Specify debugging and profiling at runtime
Syntax: DEBUG
The DEBUG command is used to specify to BLINKER that information on
debugging and profiling the application overlays is to be available at
run time.
This command enables the recording of profiling information such as
the number of loads of each overlay procedure in the overlay manager.
If this command is not used at link time the run time information
stored by the overlay manager is kept to a minimum. This means that
some of the profiling and debugging functions will not be enabled and
will return zero or null values.
The functions which DO NOT return meaningful values or have no effect
unless DEBUG is specified at link time are BLICURNME (), BLIDBGHAN (),
BLIDISSTS (), BLIDSTRC (), and BLIPRFMOD (). (see Chapter 7 BLINKER
Programming Functions).
52
Blinker Manual (c) 1990 Blink, Inc.
6.25 ENDAREA
____________
- Specify the end of an overlay area
Syntax: ENDAREA
The ENDAREA command is used to specify to the linker the end of an
overlay area, as described in the BEGINAREA section.
6.26 FILE
_________
- Specify object file(s)
Syntax: FILE
The FILE command is used to specify to the linker the names of one or
more OBJ files to be included in the output file at that point.
The default file extension of .OBJ need not be specified, and if more
than one file is specified then each file name should be separated by
a comma. The maximum length of each line in the script file will
depend on the editor you are using.
All .OBJ files listed in FILE commands are included in the linked
application, whether they are required or not.
To only include the .OBJ files needed by the specific application a
library (.LIB) file should be created using a librarian such as
Microsoft LIB.EXE. This library can then be linked to the application
using the ALLOCATE (section 6.4) or LIBRARY (section 6.28) commands
and only the required .OBJ files from the .LIB file will be linked to
the application.
BLINKER looks for each .OBJ file first in the current directory and
then in each directory path specified in the OBJ environment variable
in the order they appear (see section 3.3 "The OBJ Variable").
Alternatively, a full drive and directory path may be specified with
any or each of the file names.
6.27 HEIGHT
___________
- Specify page height of memory map reports
Syntax: HEIGHT
53
Blinker Manual (c) 1990 Blink, Inc.
The HEIGHT command is used to change the page height of the memory map
reports to the number of lines specified after the HEIGHT command. The
default is 65 lines per page.
BLINKER ignores the HEIGHT command as it is not yet supported.
6.28 LIBRARY
____________
- Specify names of one or more program libraries
Syntax: LIBRARY
The LIBRARY command is used to specify to the linker the names of one
or more program library files required by the application to link
correctly.
The default file extension of .LIB need not be specified, and if more
than one file is specified then each file name should be separated by
a comma.
This command is used outside the BEGINAREA / ENDAREA to link libraries
of code created using a library manager such as Microsoft LIB.EXE into
the root of an application. The advantage of this over FILE commands
is that only the OBJs actually required will be linked into the
application, rather than all the .OBJs if FILE commands are used.
If the library is to be overlaid, rather than placed in the root, then
the ALLOCATE command (section 6.4) should be used between the
BEGINAREA / ENDAREA instead of the LIBRARY command outside the
BEGINAREA / ENDAREA.
It should be noted that all overlay manager libraries such as
OVERLAY.LIB should be removed from the LIB commands as BLINKER's
overlay manager is linked automatically if required.
BLINKER looks for each .LIB file firstly in the current directory and
then in each directory path specified in the LIB environment variable
in the order they appear (see section 3.4 "The LIB Variable").
Alternatively, a full drive and directory path may be specified with
any or each of the file names.
For examples of using the LIBRARY command see section 5.4 - Choosing
What to Overlay.
6.29 LOWERCASE
______________
54
Blinker Manual (c) 1990 Blink, Inc.
- Specify all symbols should be converted to lowercase
Syntax: LOWERCASE
The LOWERCASE command is used to specify to the linker that all
symbols should be converted to lower case before being added to the
symbol table.
BLINKER ignores the LOWERCASE command as it is not yet supported.
6.30 MAP
________
- Specify a map file of the linked .EXE is required
Syntax: MAP [=
The MAP command is used to specify to the linker that a map file of
the linked .EXE file is required. The map file defaults to the same
name as the .EXE file with an extension of .MAP, or the name can be
specified in the MAP comand. The map file can be listed with varying
levels of detail as required.
The four options to the command are as follows:
A - All segments - lists the input program .OBJ files (modules)
with the segments of each module listed in memory address order. This
is the default option if none are specified.
G - Global (Public) symbols - lists the public symbols and their
memory addresses.
M - Modules - lists the input program .OBJ files (modules) with
all the segments and symbols in that module in memory address order.
(This is the most detailed of the options).
S - Sections - lists the input program .OBJ files (modules) with
summary information for each.
6.31 NOBELL
___________
- Suppress the beep upon completed link execution
Syntax: NOBELL
The NOBELL command is used to specify to the linker that no beep is to
sound when the link has completed execution.
55
Blinker Manual (c) 1990 Blink, Inc.
6.32 OUTPUT
___________
- Specify the name of the output executable file
Syntax: OUTPUT
The OUTPUT command is used to specify to the linker the name of the
output executable file to be created by the linker.
If no OUTPUT command is used then the linker will use the name of the
first object file appearing on a FILE command in the script file or on
the command line.
The OUTPUT file name extension does not have to be .EXE, but if no
file extension is specified then a default of .EXE is used.
6.33 OVERLAY
____________
- Specify which segment classes are to be overlaid
Syntax: OVERLAY
The OVERLAY command is used to specify to the linker which segment
class or classes from the object files are to be placed in the overlay
sections.
BLINKER ignores the OVERLAY command as it is not yet supported - only
segments of class CODE are currently overlaid.
6.34 SEARCH
___________
- Specify multiple pass search for unresolved symbols
Syntax: SEARCH
The SEARCH command is an alternative form of the LIBRARY and ALLOCATE
commands. It is used to specify to the linker that the specified
library file(s) should be processed multiple times if any symbols are
unresolved after the first pass.
The SEARCH command can be placed either in the root for non-
overlayable libraries or between the BEGINAREA / ENDAREA commands for
overlayable libraries.
It is necessary to use the SEARCH command if unresolved external
references are found in an application which links correctly with
56
Blinker Manual (c) 1990 Blink, Inc.
Microsoft LINK or PLINK86plus using an equivalent script file. This
may occur if two libraries both call each other, or one library calls
another which calls another which calls the first.
BLINKER uses the library cross reference table found in .LIB files
created by later versions of Microsoft LIB.EXE. This table virtually
eliminates the need for SEARCH and improves linking speed for most
libraries. If a .LIB file was processed with Microsoft LIB.EXE version
3.08, dated 01/29/88 or earlier, it will not have the correct format
of cross reference in it. Version 3.11, dated 03/07/88, creates the
cross reference correctly.
It is worth running libraries through the newer LIB.EXE if you have
it. The simplest way is to attempt to add a non existent OBJ file to
the library. For example, for FUNCKY.LIB (this is necessary for most
versions of FUNCky), use the command:
LIB FUNCKY+XYZ;
where XYZ.OBJ does not exist. This will create a new FUNCKY.LIB with
the cross reference, and rename the old library to FUNCKY.BAK.
It should be noted that this process will set the DOS last modified
date of the new library and increase its size a little, so the
original version should always be kept, if only in case the date and
size details are needed by the suppliers of the library for technical
support queries.
When the majority of a library is required by an application the use
of a SEARCH command in place of a LIB or ALLOCATE command can improve
the link time since BLINKER does not have to process the library cross
reference table. However, when only a minority of the library is
required, SEARCH can significantly increase the link time and the
amount of memory required to link, so it is worth experimenting with
the order of the LIB files to place the libraries containing the
unresolved externals after the libraries calling them.
Example: If you receive an error message 1115: aaaaaa (bbbbbb)
'cccccc' is an unresolved external when linking with BLINKER, but
linking with Microsoft LINK or PLINK86plus works correctly, do the
following:
1. Determine which library 'cccccc' (the missing external)
resides in.
2. Replace the LIB
the command line, with, SEARCH
57
Blinker Manual (c) 1990 Blink, Inc.
6.35 SECTION
____________
- Specify files to be overlaid
Syntax: SECTION FILE
The SECTION command is used to specify to the linker that any files
following the SECTION command until the next SECTION command or an
ENDAREA command are to be placed together in a single overlay section.
With static overlays a section is the smallest overlay unit
manipulated by the overlay manager at run time, i.e. a whole section
will be read in to memory when any part of it is required, and the
whole section is discarded when an alternative section is required.
With BLINKER dynamic overlays, SECTION commands are ignored because
all overlaying is done at the procedure level. The files listed are
processed exactly as if the command had been a FILE command.
6.36 SECTION INTO
_________________
- Specify files to be placed in an external overlay
Syntax: SECTION INTO
The SECTION INTO command is used to specify the name of an external
overlay file for the overlay section. The file may have any extension
except .EXE, and if no extension is used then .OVL is assumed. Within
a BEGINAREA block, if a FILE command is found before a SECTION INTO
command then the overlay will be made an internal overlay within the
OUTPUT file.
Once an overlay file has been specified using the SECTION INTO
command, all other overlay code will be placed in the same file until
a SECTION INTO command with a different file name is found. At this
time a new overlay file will be created.
Output may be spread between the overlay files by the use of the
SECTION INTO command. Jumping back and forth should be avoided, so
that the overlay manager does not have to keep switching overlay files
at run time.
Once an internal overlay has been created all SECTION INTOs will be
ignored and all overlaid procedures will be stored internally. Once an
external overlay has been created it is not possible to create an
internal overlay . BLINKER has a maximum of 15 external overlays in
this version.
58
Blinker Manual (c) 1990 Blink, Inc.
At application run time, 1 file handle is allocated to each overlay
file, so it may be necessary to increase the Fnnn setting in the
Clipper environment variable to leave enough file handles for the
application to run.
6.37 STACK
__________
- Specify stack size of applications EXE file
Syntax: STACK
The STACK command is used to specify to BLINKER in DECIMAL the stack
size in bytes required by the application EXE file.
Use of this command should be unnecessary with most applications, and
should be used with care. A preferable way of increasing the stack
size and therefore the maximum depth of procedure calls is to use the
BLINKER PROCEDURE DEPTH command.
BLINKER's default stack size is 2048 bytes, which corresponds to a
PROCEDURE DEPTH of approximately 20.
If the STACK command is used, please note that the size is specified
in DECIMAL, whereas the PLINK86plus stack size was specified in HEX.
Therefore, a stack size of 1000 with PLINK86plus would directly equate
to a stack size of 4096 with BLINKER.
6.38 UPPERCASE
______________
- Convert all symbols to uppercase
Syntax: UPPERCASE
The UPPERCASE command is used to specify to the linker that all
symbols should be converted to upper case before being added to the
symbol table.
BLINKER ignores the UPPERCASE command as it is the default.
6.39 VERBOSE
____________
- Display status information during linking
Syntax: VERBOSE
59
Blinker Manual (c) 1990 Blink, Inc.
The VERBOSE command is used to specify to the linker that it is to
display information regarding the current operation being performed.
This command will slow down the linking process significantly, but
provides the developer with a means of isolating the cause of a link
time error.
When VERBOSE is specified, BLINKER displays each object module and the
file containing it as it is processed. This output may be redirected
to a file using standard DOS redirection if required. For example, to
create a VERBOSE output from the link script file TEST.LNK and
redirect the output to a file TEST.MSG:
BLINKER @TEST VERBOSE >TEST.MSG
or
BLINKER @TEST >TEST.MSG
(where VERBOSE is a command in the .LNK file)
TEST.MSG may now be viewed using the DOS TYPE command or any editor or
word processor which reads normal ASCII text files.
6.40 WIDTH
__________
- Change the page width of the memory map file
Syntax: WIDTH
The WIDTH command is used to change the page width of the memory map
reports to the number of characters per line specified after the WIDTH
command. The default is 80 characters per line.
BLINKER ignores the WIDTH command as it is not supported in this
version.
6.41 WORKFILE
_____________
- Specify drive, path,and file name of temp work file
Syntax: WORKFILE [d:][path]
The WORKFILE command is used to specify to the linker the drive, path
and file name of the temporary work file to use if one is required.
60
Blinker Manual (c) 1990 Blink, Inc.
BLINKER ignores the WORKFILE command as it is not supported in this
version.
61
Blinker Manual (c) 1990 Blink, Inc.
_________________________________________________________________________
| |
7. BLINKER Programming Functions
| |
_________________________________________________________________________
| |
7.1 Overview
_____________
BLINKER provides a number of functions to the Clipper application
developer to increase control over the run time overlay environment
and to provide profiling and debugging information to the developer.
These functions may be used with an existing Clipper application to
monitor and record its performance in both memory usage and speed
while it is executing, in order to fine tune the application. They may
also be used while developing a new application to ensure that the
design and implementation decisions being made are not adversely
affecting the performance of the application.
Chapter 10, - Using the BLINKER Profiler - shows examples of
incorporating these functions into a profiler which may be used with
any application with the minimum of code modification.
The functions are written using Clipper's Extend system, so may be
accessed directly from a normal Clipper program.
All the functions which produce output take a file handle as an
optional parameter, and all output from the function will be sent to
that file handle. The handle is not validated, and should be either 1
to send output to the screen, 2 to send output to the standard error
device, 4 to send output to the printer, or the handle of a file
opened by the application with FOPEN ().
The default handle may be set at link time using the BLINKER DEBUG
HANDLE command or in the application using the Debug Handle function
(BLIDBGHAN ()) detailed below.
If no handle is specified then the output is sent to DOS file handle 1
(the screen).
These functions are always available in applications prepared with
BLINKER, but it should be noted that some of them will not be enabled
unless the DEBUG command (see section 6.24 DEBUG) has been specified
at link time.
The functions which only return meaningful values when DEBUG is
specified in the link file are BLICURNME (), BLIDBGHAN (), BLIDISSTS
(), BLIDISTRC (), and BLIPRFMOD (). Those functions which do not
62
Blinker Manual (c) 1990 Blink, Inc.
return values, e.g. BLIOVLCLR () and BLIMEMPAK () will still operate
without DEBUG.
Each function is described here with the effect that it will have on
the run time overlay environment, an example of how to use it, and a
description of when it may be used (if there are any restrictions).
7.2 BLICURCAL () - Current Procedure Calls
_____________________________________________
This function returns the number of times the current procedure has
been called since the application started.
An example using this function is shown below.
*
* Get the number of calls to the current procedure
*
* BLICURCAL ()
*
? "This procedure has been called "
?? BLICURCAL (), " times"
7.3 BLICURDSK () - Current Procedure Disk Loads
__________________________________________________
This function returns the number of times the current procedure has
been loaded from disk since the application started.
An example using this function is shown below.
*
* Get the number of loads of the current procedure
*
* BLICURDSK ()
*
? "This procedure has been loaded from disk "
63
Blinker Manual (c) 1990 Blink, Inc.
?? BLICURDSK (), " times"
7.4 BLICURNME () - Current Procedure Name
____________________________________________
This function returns the name of the procedure about to be loaded by
the overlay manager when profiling mode is enabled.
Note: This function is only active if the DEBUG command was specified
at link time, otherwise it returns a null string.
An example using this function is shown below.
*
* Get the name of the procedure about to be loaded
*
* BLICURNME ()
*
? "About to load procedure ", BLICURNME ()
7.5 BLICURSIZ () - Current Procedure Size
____________________________________________
This function returns the size in bytes of the current procedure.
An example using this function is shown below.
*
* Get the size of the current procedure
*
* BLICURSIZ ()
*
? "This procedure is ", BLICURSIZ (), " bytes long"
7.6 BLIDBGHAN () - Debug Handle
__________________________________
64
Blinker Manual (c) 1990 Blink, Inc.
This function is used to get or set the BLINKER overlay manager debug
handle. It returns the previous debug handle, and takes as an optional
parameter the new handle it should be set to.
The handle defaults to 1 for the screen unless it is overridden at
link time using the BLINKER DEBUG HANDLE command or at run time using
the /DHn setting in the BLINKER environment variable.
The new handle is not validated and may be either 1 to send output to
the screen, 2 to send output to the standard error device, 4 to send
output to the printer, or the handle of a file opened by the
application with FOPEN ().
Note: This function is only active if the DEBUG command was specified
at link time, otherwise it returns a zero value.
An example using this function is shown below.
*
* Get the current debug handle
*
* BLIDBGHAN ([handle])
*
? "The debug handle is currently", BLIDBGHAN ()
*
* Set the current debug handle to the printer
*
BLIDBGHAN (4)
7.7 BLIDEMCAL () - Demonstration Calls
_________________________________________
This function returns the demonstration procedure call limit of the
application if it was set at link time, and returns an integer number
of calls between 0 (no limit was set) and 65535.
It may also be used to extend the call limit to allow the current task
to finish by passing the new limit as a parameter to the function.
65
Blinker Manual (c) 1990 Blink, Inc.
Since this is the new limit it will always be greater than the value
returned.
An example using this function is shown below.
*
* Get the procedure call limit and extend it
* by 100 calls
*
* BLIDEMCAL ()
*
TMPDEMCAL = BLIDEMCAL () && Get the calls limit
IF TMPDEMCAL > 0
? "The calls limit is", TMPDEMCAL
? "It will be extended by 100 calls"
BLIDEMCAL (TMPDEMCAL + 100)
ENDIF
7.8 BLIDEMDTE () - Demonstration Date
________________________________________
This function returns the demonstration date limit of the application
if it was set at link time, and returns it as a string in the form
YYYYMMDD.
A null string will be returned if the demonstration date limit has not
been set.
An example using this function is shown below.
*
* Display the expiration date if there is one
*
* BLIDEMDTE ()
66
Blinker Manual (c) 1990 Blink, Inc.
*
TMPDEMDTE = BLIDEMDTE () && Get the date limit
IF LEN (TMPDEMDTE) > 0
? "The expiration date of this program is "
?? TMPDEMDTE
ENDIF
7.9 BLIDEMMIN () - Demonstration Minutes
___________________________________________
This function returns the demonstration time limit in minutes of the
application if it was set at link time, and returns an integer number
of minutes between 0 (not set) and 65535.
It may also be used to extend the limit to allow the current task to
finish by passing the new limit as a parameter to the function. Since
this is the new limit it will always be greater than the value
returned.
An example using this function is shown below.
*
* Get the time limit and extend it by 2 minutes
*
* BLIDEMMIN ()
*
TMPDEMMIN = BLIDEMMIN () && Get the time limit
IF TMPDEMMIN > 0
? "The time limit is", TMPDEMCAL, "minutes"
? "It will be extended by 2 minutes"
BLIDEMCAL (TMPDEMMIN + 2)
ENDIF
67
Blinker Manual (c) 1990 Blink, Inc.
7.10 BLIDISFRG () - Display Fragmentation
___________________________________________
This function is used to display a summary of dynamic memory to show
the degree of fragmentation, and takes as an optional parameter the
output destination file handle. Each character position represents up
to 512 bytes, and adjacent equal characters represent contiguous
blocks larger than 512 bytes.
Note: This feature is only supported with Clipper Summer '87.
The * and o characters are used to indicate blocks of free memory
which are unused by Clipper, and the two graphics characters ² and ±
are used to indicate blocks of memory which are in use, i.e. have been
allocated. (A key is shown below the memory map).
The reason for having two different characters for free blocks and two
different characters for used blocks is to show where a free or used
area is made up of more than one block of memory. If only one
character was used for each then the display would not show the full
extent of fragmentation of memory into very small blocks.
The relative sizes of blocks are shown by identical repeated
characters, since a single character indicates a memory block of less
than 512 bytes, and a row of four blocks indicates a memory block of
approximately 2 Kb.
The relative fragmentation is shown by the proportion of free blocks
to used blocks and by the alternation between free and used blocks
throughout the display.
Once free areas are separated by used areas the free areas become
virtually unusable except for the storage of small temporary values,
which is why MEMORY (0) gradually deteriorates and operations which
require larger blocks of memory such as MEMOEDIT () or indexing will
then fail.
The BLIDISFRG () function may be used during the execution of an
application to monitor the fragmentation of memory as execution
continues. It may also be used to view the improvements gained using
the BLINKER MEMORY PACK command and the BLIMEMPAK () function.
An example using this function is shown below.
*
* Display the memory fragmentation
*
68
Blinker Manual (c) 1990 Blink, Inc.
* BLIDISFRG ([handle])
*
BLIDISFRG (4) && Send to the printer
7.11 BLIDISOVL () - Display All Overlays
__________________________________________
This function is used to display status information about all the
overlays in the application, and takes as an optional parameter the
output destination file handle.
Note: A procedure name of "Non-Clipper" will be displayed for overlays
which do not have a name available at run time.
Note: This function is only active if the DEBUG command was specified
at link time, otherwise it does nothing.
An example using this function is shown below.
*
* Display all the overlays
*
* BLIDISOVL ([handle])
*
BLIDISOVL (4) && Send to the printer
An example of the output would be:
Procedure Size Active Calls Loads
INV001SCR 01719 N 00010 00002
ENQ001SCR 03442 N 00000 00000
REP001LIN 00345 Y 00005 00001
REP001HDG 00032 N 00002 00001
REP001FTG 00086 Y 00001 00001
Non-Clipper 00102 N 00003 00001
69
Blinker Manual (c) 1990 Blink, Inc.
7.12 BLIDISSTS () - Display Overlay Status
____________________________________________
This function is used to display status information about all the
overlays currently in memory, and takes as an optional parameter the
output destination file handle.
Note: A procedure name of "Non-Clipper" will be displayed for overlays
which do not have a name available at run time.
Note: This function is only active if the DEBUG command was specified
at link time, otherwise it does nothing.
An example using this function is shown below.
*
* Display the overlay status
*
* BLIDISSTS ([handle])
*
BLIDISSTS (4) && Send to the printer
An example of the output would be:
Procedure Size Active Calls Loads
REP001LIN 00345 Y 00005 00001
REP001HDG 00032 N 00002 00001
REP001FTG 00086 Y 00001 00001
Non-Clipper 00102 N 00001 00001
7.13 BLIDISTRC () - Display Call Trace
________________________________________
This function is used to display a trace of the overlay procedures
called to reach the active procedure. This is to the exclusion of any
procedures in the root. It takes as an optional parameter the output
destination file handle.
Note: A procedure name of "Non-Clipper" will be displayed for overlays
which do not have a name available at run time.
70
Blinker Manual (c) 1990 Blink, Inc.
Note: This function is only active if the DEBUG command was specified
at link time, otherwise it does nothing.
An example using this function is shown below.
*
* Display a call trace
*
* BLIDISTRC ([handle])
*
BLIDISTRC () && Send it to the default
An example of the output would be:
Called by: REPGENDET
Called by: REPGENPAG
7.14 BLIERRNUM () - BLINKER Error Number
__________________________________________
This function returns the BLINKER run time error number, and is for
use in the BLINKER error handler BLERRPRG (in normal operation the
value returned is zero, meaning no error).
For details of the BLINKER run time errors see section 12.4 Run Time
Error Messages.
An example using this function is shown below.
*
* Get the BLINKER error number
*
* BLIERRNUM ()
*
? "The BLINKER error number is ", BLIERRNUM ()
71
Blinker Manual (c) 1990 Blink, Inc.
7.15 BLIERRPRM () - BLINKER Error Parameter
_____________________________________________
Some of the BLINKER run time errors refer to a particular file name,
and this function returns this name for use in the error message.
For details of the BLINKER run time errors see section 12.4 Run Time
Error Messages.
An example using this function is shown below.
*
* Get the BLINKER error parameter
*
* BLIERRPRM ()
*
? "The file causing the BLINKER error is ", BLIERRPRM ()
7.16 BLILSTFRG () - List Fragmentation
________________________________________
This function is used to list each block of dynamic memory to show the
degree of fragmentation. Each block is listed on a separate line with
its address in memory, its size and whether it is in use or not. The
function takes as an optional parameter the output destination file
handle.
Note: This feature is only supported with Clipper Summer '87.
An example using this function is shown below.
*
* List the Fragmentation
*
* BLILSTFRG ([handle])
*
BLILSTFRG (4) && Send to the printer
An example of the output would be:
72
Blinker Manual (c) 1990 Blink, Inc.
Address Size In Use
8198:0000 00018 Y
8198:0014 00184 N
8198:00EA 00058 Y
8198:0120 60020 N
7.17 BLIMEMAVL () - Total Memory Available
____________________________________________
This function returns the total dynamic memory available in bytes.
Dynamic memory is the memory used by Clipper to store all temporary
values of variables and buffers while an application is running.
An example using this function is shown below.
*
* Get the total available memory
*
* BLIMEMAVL ()
*
? "There are", BLIMEMAVL ()
?? " bytes available in Clipper's free pool"
7.18 BLIMEMBLK () - Memory Available in Blocks
________________________________________________
This function returns the total dynamic memory available in kilobytes
in blocks at least as large as the block size in kilobytes specified
as a parameter. Dynamic memory is the memory used by Clipper to store
all temporary values of variables and buffers while an application is
running.
Note: This feature is only supported with Clipper Summer '87.
If no parameter is specified then a default block size of 4 kb is
used, which simulates the value returned by a call to Clipper's MEMORY
(0). In all cases the function will emulate MEMORY (0) and attempt to
allocate blocks of size 63kb, then 48kb, then 32kb, then 16kb, then 8,
73
Blinker Manual (c) 1990 Blink, Inc.
4, 2 and 1kb until no block larger or equal to the parameter or
default can be allocated. The value returned will be the total size of
the blocks successfully allocated.
BLIMEMBLK () executes many times faster than MEMORY (0), so may be
used to monitor memory in places where MEMORY (0) is found to slow the
application too much, for example during indexing or profiling.
An example using this function is shown below.
*
* Get the available memory in minimum of 8kb blocks
*
* BLIMEMBLK ()
*
? "The memory available in at least 8Kb blocks is"
?? BLIMEMBLK (8), " kb"
7.19 BLIMEMMAX () - Maximum Memory Block Size
_______________________________________________
This function returns the size in bytes of the largest available block
of dynamic memory. Dynamic memory is the memory used by Clipper to
store all temporary values of variables and buffers while an
application is running.
An example using this function is shown below.
*
* Get the size of the largest available block
*
* BLIMEMMAX ()
*
? "The largest available block of memory is"
?? BLIMEMMAX (), " bytes"
74
Blinker Manual (c) 1990 Blink, Inc.
7.20 BLIMEMPAK () - Memory Pack Frequency
___________________________________________
This function is used to get or set the frequency of procedure calls
with which the BLINKER overlay manager packs free dynamic memory to
reduce fragmentation, returns the previous pack frequency, and takes
an optional parameter of the new frequency to set it to.
Note: This feature is only supported with Clipper Summer '87.
BLINKER defaults to maximum speed and a setting of zero for the
frequency, which means it performs no packing of free dynamic memory
to prevent fragmentation. BLINKER may be told to automatically pack
memory after every n procedure calls, either at link time using the
BLINKER MEMORY PACK command (see section 6.10 BLINKER MEMORY PACK) or
at application run time using the BLIMEMPAK () function.
The effect of this function depends on the value of the parameter
passed, but it always returns the current pack frequency , i.e. the
BLINKER overlay manager will pack free dynamic memory every time this
number of procedures has been called.
If no parameter is specified then no action will be taken by the
function.
If a parameter value of -1 is passed the overlay manager performs a
memory pack immediately and leaves the pack frequency unchanged. This
is particularly useful following a call to BLIOVLCLR () to clear
inactive overlays before DBEDIT, MEMOEDIT, reindexing and other memory
intensive routines.
A parameter of 0 switches off the memory packing altogether, and any
other value sets the packing frequency to that value.
An example using this function is shown below.
*
* Get the BLINKER memory pack frequency
*
* BLIMEMPAK ()
*
? "Packing currently occurs after every "
?? BLIMEMPAK (), " calls"
75
Blinker Manual (c) 1990 Blink, Inc.
*
* Set to every 10 procedure calls
*
BLIMEMPAK (10)
7.21 BLIMEMSIZ () - Total Memory Size
_______________________________________
This function returns the total size in bytes of the dynamic memory
area. Dynamic memory is the memory used by Clipper to store all
temporary values of variables and buffers while an application is
running.
An example using this function is shown below.
*
* Get the total free pool size
*
* BLIMEMSIZ ()
*
? "The total size of Clipper's free pool is"
?? BLIMEMSIZ (), " bytes"
7.22 BLIMEMUSE () - Total Memory Used
_______________________________________
This function returns the size in bytes of all the dynamic memory
currently in use. Dynamic memory is the memory used by Clipper to
store all temporary values of variables and buffers while an
application is running.
An example using this function is shown below.
*
* Get the amount of dynamic memory in use
*
76
Blinker Manual (c) 1990 Blink, Inc.
* BLIMEMUSE ()
*
? BLIMEMUSE (), "bytes of dynamic memory are "
?? "currently in use"
7.23 BLIOVLCLR () - Clear Inactive Overlays
_____________________________________________
This function is used to force the BLINKER overlay manager to clear
out or discard all inactive overlay procedures from the overlay pool
and return the memory used by them to Clipper.
This may be used in the main module of an application to ensure that
Clipper has the maximum amount of dynamic memory available before
executing another overlay.
Once all overlays are flushed, the overlay operating size is reset to
the maximum of the default size set when the application started or
the total size of the active overlays. The default size when the
application starts is the most recent of the link time BLINKER OVERLAY
OPSIZE
environment variable.
An example using this function is shown below.
*
* Clear all inactive overlays
*
* BLIOVLCLR ()
*
BLIOVLCLR ()
7.24 BLIOVLOPS () - Overlay Pool Operating Size
_________________________________________________
This function returns the operating size in KB of the overlay pool.
This is set at link time using the BLINKER OVERLAY OPSIZE
command or at run time using the /OOnn parameter in the BLINKER
environment variable. (see section 6.14 BLINKER OVERLAY OPSIZE).
77
Blinker Manual (c) 1990 Blink, Inc.
This size is the maximum amount of memory which BLINKER will allocate
from Clipper for overlays. Once BLINKER has used this much memory for
overlays it will discard unused overlays to free up space for the next
overlay, rather than allocating more dynamic memory from Clipper to
store the overlay.
An example using this function is shown below.
*
* Get the overlay pool operating size.
*
* BLIOVLOPS ()
*
? "The overlay pool operating size is "
?? BLIOVLOPS (), " KB"
7.25 BLIOVLSIZ () - Overlay Pool Current Size
_______________________________________________
This function returns the current size of the overlay pool in KB.
This value reflects the exact amount of memory being used by BLINKER
for overlays at the current time. At the start of an application this
will be zero, and this value will increase until it reaches the
operating size set by BLINKER OVERLAY OPSIZE
BLIOVLOPS ().
Once it has reached this size it will stabilize for the rest of the
application until a call to BLIOVLCLR (). When a call to BLIOVLCLR ()
is made, all inactive overlays are discarded and the memory is
returned to Clipper, so the current size will decrease to the size of
just the active overlays. In the best case of BLIOVLCLR () being
called from the root then BLIOVLSIZ () should actually return to zero.
An example using this function is shown below.
*
* Get the current overlay pool size.
*
78
Blinker Manual (c) 1990 Blink, Inc.
* BLIOVLSIZ ()
*
? "The current overlay pool size is"
?? BLIOVLSIZ (), " KB"
7.26 BLIPRFMOD () - Profiling Mode
____________________________________
This function is used to get or set the BLINKER overlay manager
profiling mode. It returns the previous profile mode, and takes as an
optional parameter the new mode to set it to.
Note: This function is only active if the DEBUG command was specified
at link time, otherwise it does nothing.
The default mode is off (.F.), but if the mode is set to on (.T.) then
each time an overlaid procedure is called the BLINKER overlay manager
will call the Clipper procedure BLPRFPRG.
A dummy procedure BLPRFPRG.PRG consisting of a few print statements
using some of the BLINKER profiling functions is automatically linked
to the application by BLINKER. This may be replaced by including a
.OBJ or .LIB file containing a different procedure BLPRFPRG in the
script file so that it is linked in preference to the dummy one.
This procedure may then call the BLINKER overlay manager function
BLICURNME () to obtain the name of the procedure being called, as well
as any of the other functions in the BLINKER programming interface.
The BLPRFPRG procedure may not be overlaid, but calling of other
overlaid procedures from within this procedure is allowed. It should
be noted, however, that calling overlaid procedures from within the
profiler will tend to distort the profiling figures for those
functions.
The procedure BLPRFPRG allows the developer to create a customized
overlay profiling program. This program could record other information
about each overlay procedure such as the time each procedure was last
called, the amount of time it was used for and the number of times it
called other procedures.
A profiler developer would probably maintain an array of the procedure
names returned by the overlay manager and could use ASCAN () to search
the array to find the entry for the called procedure.
79
Blinker Manual (c) 1990 Blink, Inc.
Parallel arrays could be maintained for each item related to the
procedure, or all the items could be combined into a string. An array
of strings could then be used to store them all.
For more details on the comprehensive profiler provided in source form
on the distribution diskette please refer to Chapter 10 - Using the
Blinker Profiler.
An example using this function is shown below.
*
* Get the current profiling mode
*
* BLIPRFMOD ([mode])
*
? "Profiling is ", IIF (BLIPRFMOD (),"ON","OFF")
*
* Set the current profiling mode on
*
BLIPRFMOD (.t.)
7.27 BLISERNUM () - Serial number
___________________________________
This function is used to examine a serial number and other information
of up to 50 characters encrypted into the executable file at link
time.
This information is encrypted into the executable file and could be
used to hide a serial number and licensee number in the executable
file as a form of copy protection.
The information is stored as a string, so the rest of the line in the
script file up to 50 characters is copied directly into the .EXE file
and is returned in exactly the same format at run time.
For example, to encrypt an application with a serial number of
00100001, a 5 user license and a licensee name of Blink, Inc. use the
following command:
80
Blinker Manual (c) 1990 Blink, Inc.
BLINKER EXECUTABLE SERIAL 00100001 5 Blink, Inc.
At application run time these values can be examined by assigning the
serial number to a string and then manipulating it using SUBSTR, for
example:
TMPSERNUM = BLISERNUM ()
? "Serial number:", SUBSTR (TMPSERNUM, 1, 8)
? "No. of Users :", VAL (SUBSTR (TMPSERNUM, 10, 1))
? "Licensed to :", SUBSTR (TMPSERNUM, 12, 20)
7.28 BLISTRFRG () - String of Fragmentation
_____________________________________________
This function returns a string containing a summary of dynamic memory
to show the degree of fragmentation. Each character position
represents up to 512 bytes, and adjacent equal characters represent
contiguous blocks larger than 512 bytes.
Note: This feature is only supported with Clipper Summer '87.
It takes an optional parameter of a four character string containing
two characters to represent free blocks and two characters to
represent used blocks. The layout and meaning of the display is
detailed in section 7.10 - BLIDISFRG ().
An example using this function is shown below.
*
* Get the string showing memory fragmentation
* Use '*' for all free blocks, '-' for all used
*
* BLISTRFRG ()
*
TMPSTRFRG = BLISTRFRG ("**--")
? "The state of dynamic memory is currently :"
? TMPSTRFRG
81
Blinker Manual (c) 1990 Blink, Inc.
7.29 BLITOTACT () - Total Active Procedures
_____________________________________________
This function returns the total number of procedures handled by the
BLINKER overlay manager currently active in the application.
An example using this function is shown below.
*
* Get the current number of active procedures.
*
* BLITOTACT ()
*
? "There are", BLITOTACT (), "procedures currently active"
7.30 BLITOTCAL () - Total Procedure Calls
___________________________________________
This function returns the total number of procedure calls handled by
the BLINKER overlay manager since the application was loaded.
An example using this function is shown below.
*
* Get the total number of procedure calls
*
* BLITOTCAL ()
*
? "Total procedure calls: ", BLITOTCAL ()
7.31 BLITOTDSK () - Total Procedure Disk Loads
________________________________________________
This function returns the total number of procedure calls handled by
the BLINKER overlay manager since the application was loaded which
required the procedure to be loaded from disk.
An example using this function is shown below.
82
Blinker Manual (c) 1990 Blink, Inc.
*
* Get the total number of procedure disk loads.
*
* BLITOTDSK ()
*
? "The total procedure disk loads is:", BLITOTDSK ()
7.32 BLITOTLOD () - Total Loaded Procedures
_____________________________________________
This function returns the total number of procedures handled by the
BLINKER overlay manager currently loaded in memory.
An example using this function is shown below.
*
* Get the current number of loaded procedures
*
* BLITOTLOD ()
*
? "Total procedures currently loaded: ", BLITOTLOD ()
7.33 BLITOTSIZ () - Total Procedure Size
__________________________________________
This function returns the total size in KB of all the procedures
handled by the BLINKER overlay manager since the application was
loaded.
An example using this function is shown below.*
* Get the total procedure size
*
* BLITOTSIZ ()
*
83
Blinker Manual (c) 1990 Blink, Inc.
? "The total procedure size in bytes is :", BLITOTSIZ ()
_________________________________________________________________________
| |
8. Creating Demonstration Versions
| |
_________________________________________________________________________
| |
8.1 Overview
_____________
BLINKER allows the developer to create a demonstration version of an
application at link time. It does this by providing commands which
specify a maximum number of procedure calls to execute, a maximum time
in minutes for the application to run, an expiration date for the
software, or any combination of the three.
The default BLINKER error handler BLERRPRG, the source of which is on
the distribution diskette in file BLERRPRG.PRG (for Clipper Summer
'87) and BLERRC50.PRG (for Clipper 5.0), is automatically linked to
the application by BLINKER. This procedure is called when an error
occurs in the BLINKER overlay manager or when a demonstration limit
set at link time has expired.
The error handler sets up the appropriate error message for the error
number returned by the function BLIERRNUM (), in some cases using the
function BLIERRPRM () to obtain the name of the offending item. In the
case of Clipper Summer '87 it then calls MISC_ERROR with a procedure
name of BLINKER, a line number which is the error number, and the
appropriate error message. In the case of Clipper 5.0 it creates a new
error object which is passed as the argument to the default error
handler block.
This handler may be replaced with another UDF or procedure with the
same name (BLERRPRG) written in Clipper to handle the expiration and
error messages with a more meaningful message and normal close down of
the application. This is done by simply including the replacement
procedure in one of the .OBJ or .LIB files at link time.
It is recommended that if the BLERRPRG procedure is to be changed then
the modified version should be included in the developer's
ERRORSYS.PRG file in the case of Clipper Summer '87, and in the
developer's other error handling routines file in the case of Clipper
5.0.
Care should be taken when overlaying the error handler in the case of
the potential error 1201: cannot find overlay file in the current
PATH. This can cause an endless loop as the BLINKER overlay manager
84
Blinker Manual (c) 1990 Blink, Inc.
tries to load the error handler and then calls it to indicate the
error.
The developer may wish to handle this particular error in a different
way to avoid this problem, or may just ensure that the overlay file
can be found, e.g. by making it an internal overlay.
Note: the demonstration restrictions are only checked during overlaid
procedures as BLINKER has no control over procedures in the root.
Therefore, if an application is to be limited using these features it
must contain at least one overlaid procedure or function which is
called regularly.
8.2 Demonstration Call Limit
_____________________________
An application may be restricted so that after the overlay manager has
loaded and called a specified number of procedures or functions it
will call the error handler procedure BLERRPRG which can then end the
application.
To restrict the number of calls for an application include the BLINKER
DEMONSTRATION CALLS
The number of calls is specified in decimal and may be up to 65535
(any larger number will be ignored).
8.3 Demonstration Date Limit
_____________________________
An application may be restricted so that after a specified date the
application will no longer run. In this case the overlay manager will
call the error handler procedure BLERRPRG which can then end the
application.
To set the expiration date for an application include the BLINKER
DEMONSTRATION DATE mm/dd/yy command in the link script file, where mm
represents the month, dd represents the day and yy represents the year
after which the application will no longer run.
8.4 Demonstration Time Limit
_____________________________
An application may be restricted so that after the overlay manager has
been loaded for a specified time in minutes it will no longer run. In
this case the overlay manager will call the error handler procedure
BLERRPRG which can then end the application.
85
Blinker Manual (c) 1990 Blink, Inc.
To restrict the execution time for an application include the BLINKER
DEMONSTRATION MINUTES
number of minutes is specified in decimal and may be up to 65535 (any
larger number will be ignored).
Note: The demonstration version of BLINKER always generates
applications with this value set to 5.
86
Blinker Manual (c) 1990 Blink, Inc.
_________________________________________________________________________
| |
9. Getting More Out of BLINKER
| |
_________________________________________________________________________
| |
9.1 Overview
_____________
This chapter summarizes some of the ways in which an application may
be designed or modified for use with BLINKER to drastically reduce its
memory requirement at run time and make full use of the features
provided by BLINKER.
9.2 Incremental Linking During Development
__________________________________________
During development with incremental linking keeping many small Clipper
.OBJ files gives the fastest Edit, Compile, Link and Run cycle. This
requires more memory for the application to run while developing, but
this should be an acceptable tradeoff as development machines usually
have plenty more memory available than the destination machines.
The first time an application is linked incrementally BLINKER creates
an incremental file with the same name as the .EXE with an extension
of .BIF (BLINKER Incremental File). This file records the information
needed to perform subsequent incremental links for that application.
It should be noted that this version of BLINKER will only link Clipper
compiled code incrementally. If any other non-Clipper files are
recompiled then an appropriate message is displayed and a full link
is performed.
When changes are made to individual .PRGs and they are compiled
BLINKER will detect, based on their date and time, the .OBJs which
have changed and relink only those into the application.
Changes which may be made to the .PRGs without a full link being
required include the addition, deletion or renaming of variables,
addition, deletion or changing of lines of code, and addition or
deletion of references to other functions or procedures present in the
application.
When the initial link is performed the .EXE and .OVL files created are
padded with empty space to allow modified procedures which have become
larger to be fitted into the output file without adjusting the rest of
the files. This padding defaults to a size of 128 bytes per procedure,
but may be changed using the script file command BLINKER INCREMENTAL
PAD
each procedure.
87
Blinker Manual (c) 1990 Blink, Inc.
If the size of an updated procedure exceeds the old size plus the
padding then BLINKER will display a message indicating that this has
happened and force a full link of the application to recreate the .EXE
with the new .OBJs. If this happens frequently because code is
continually being added then it is advisable to increase the PAD value
to increase the number of incremental links which may be performed
before a full link is required.
Other times when a full link is forced are when a new procedure is
added to the .OBJ, and when a reference to a new function or procedure
in a library is added which has not been referenced in the application
before.
The quickest way to force a full link at any time is to delete the
.BIF file
Note: When performing an incremental link BLINKER only relinks the
changed .OBJs and does NOT perform any of the other functions
specified in the link file such as setting the CLIPPER environment
variable or the MEMORY PACK frequency. These values remain the same as
they were for the last full link. For BLINKER to perform these
functions a full link must be forced by deleting the .BIF file.
9.3 Reduce the Number of Clipper OBJs
______________________________________
When it comes to the final link for the application, or during
development as a progress check, reduce the number of Clipper .OBJs,
and therefore FILE commands in your script file, to a minimum -
ideally only one. The more .OBJs you have in a script file, the more
memory you are likely to be taking up with duplicate entries in the
Clipper symbol table.
For example, if you have 10 .OBJs each using variables X and Y, there
will be 20 entries in the Clipper symbol table for X and Y, two for
each .OBJ. If there is only one .OBJ there are only 2 symbol table
entries.
Each symbol entry takes 16 bytes in the root, however long the name
and regardless of whether or not the procedure or function is
overlaid. So in the above example, which only uses 2 variable names,
the symbol table with 10 .OBJs would occupy 320 bytes in the root
instead of only 32 bytes with a single .OBJ. Multiply this by the
number of .OBJs and variables in your application and you begin to get
some idea of the memory savings to be made by combining .OBJs.
Similarly, if you have a procedure called SAYPROMPT which is called
from all 10 .OBJ's then there will be 10 entries for it in the symbol
88
Blinker Manual (c) 1990 Blink, Inc.
table, whereas if all the code was in one .OBJ then there would only
be one symbol table entry.
The only limiting factor with combining .OBJ files is the Clipper
Summer '87 limit of 243 procedures per .OBJ. file.
It is not necessary to reduce the number of .PRG files in order to
reduce the number of .OBJ files, and having one huge .PRG file could
obviously prove unwieldy for editing purposes. Instead use a .CLP file
to compile multiple .PRGs into a single .OBJ for the final
application. A .CLP file is a script for Clipper in the same way as an
.LNK file is a script for BLINKER. It is created in the same way using
your preferred editor, and contains a list of .PRG files to be
included in a single .OBJ file.
9.4 Set the Clipper Environment Variable
_________________________________________
Set your Clipper environmental variables, either using the BLINKER
EXECUTABLE CLIPPER command in your script file or with the SET CLIPPER
command at the DOS prompt. The amount of memory rendered unavailable
to the application by not setting the R and V parameters correctly can
be significant and is easily avoidable.
Note: The values detailed here are applicable to Clipper Summer '87,
please refer to the Clipper 5.0 manual to check which ones are
applicable to 5.0.
Clipper's free pool of dynamic memory is the memory left after the
application has loaded, Clipper has taken 50 or 60 Kb at start up for
its own internal use, and the memory for the V and R areas has been
allocated. To obtain the maximum size free pool it is therefore
necessary to minimise the size of the V and R areas (without causing
the application to fail, of course).
The V area is used to store information about the active variables in
an application. A V area of 10 will allow approximately 500 active
variables - note that this is the number of active, rather than the
total number of, variables in the application. If the V area is set
too low Clipper will display the specific error message OUT OF MEMORY
(MV). If the V area is set too high then the memory in excess of the
required amount will be unused and unavailable to the application i.e.
wasted.
It is a common misconception that the R area is only used for DOS run
commands so can be set to 0. If you set R to 0 it actually defaults to
16. It is important to set the R area to a minimum value determined by
testing. If it is not set the R area defaults to a value related to
89
Blinker Manual (c) 1990 Blink, Inc.
the available memory on the machine on which the application is
running, which can have undesirable consequences.
For example, if the development machine has more available memory than
the machine(s) on which the application is to be run, the application
may fail with an out of memory error during reindexing on site and yet
work perfectly during testing. This is often the case when the
application is developed on a standalone machine for use on a network.
The network software reduces the available memory on the machines on
site, so the R area shrinks and is no longer sufficient to reindex
successfully.
Conversely, if the memory available on the site machine is greater
than that available on the test machine, the memory allocated to the R
area may be more than is required. Again, this memory would be more
use if made available to the application than trapped unused in the R
area. Don't leave the successful operation of your program to chance -
determine the required R value by testing and set the R area to a
fixed value (preferably a multiple of 4 for reasons of buffering).
We have found in practice that an R setting of 16 is suitable and
reliable for small to medium sized applications and data files, but
large applications or those using data files of more than 10,000
records may need to go to a setting of 32.
It is always advisable to disable Expanded / Extended memory usage by
Clipper with Summer '87. If this is not done then indexes may be
corrupted when Clipper uses this memory in conjunction with certain
Expanded / Extended memory drivers, or RUN errors may occur. Since you
never know what combination of software / hardware clients will have
on their machines, it's better to play safe. To disable Clipper usage
of Expanded / Extended memory set the E parameter to 0.
Never set F to an even value. There is an inconsistency in certain
versions of DOS 3.3 which can cause 64K of memory to be mysteriously
rendered unavailable to the application when an even number of files
is used.
The X parameter may be used to exclude the specified amount of memory
from being allocated and used by the Clipper application.
This parameter is primarily for testing purposes. When you use this
parameter and execute an application, the program allocates memory as
if the amount of memory specified is not available. This can be used
to simulate running the program on a network or with a TSR loaded.
For example, if you enter "X128" for this parameter, and your computer
contains 640 Kb of memory, when you execute a Clipper program the
90
Blinker Manual (c) 1990 Blink, Inc.
program will allocate memory as though the computer only contains 512
Kb of memory.
9.5 Reduce Memory Fragmentation
________________________________
Clipper uses dynamic memory to store the majority of the variable
values in a Clipper program, and this memory can become fragmented
during the life of a program. The unused parts are continually being
divided up to store temporary values which become interspersed with
ever smaller blocks of free memory until the available memory as
returned by Clipper's MEMORY (0) function reaches zero, after which
the program will fairly soon run out of memory.
Clipper's MEMORY (0), although not very accurate or consistent, should
always be watched during development to ensure that the figure is not
dropping too low. MEMORY (0) only recognises blocks of memory of at
least 4 Kb, so even if there are 50 blocks of 2 or 3 Kb available
MEMORY (0) will still return 0. Typically an application has a
possibility of failing after prolonged use if the figure returned by
MEMORY (0) drops below around 20 Kb.
Where possible, avoid the use of macros to create variables on the fly
which have not been explicitly named in the program. When this happens
Clipper creates small blocks of used memory to store the variable name
which are not released when the values stored in the variables to
which they refer are released. These blocks become scattered around
the free pool preventing adjacent free blocks from being joined
together again.
Rather declare each variable name as PRIVATE at the start of the
procedure or use an array to store the values, both of which ensure
that that there is a valid entry in the symbol table for each variable
name used.
The same applies for using macro expansions to call procedures,
wherever possible include an EXTERNAL declaration for the procedures
which may be called to ensure that they have entries in the symbol
table.
If this cannot be done, then add a BLIMEMPAK (-1) call just before the
macro expansion. This will pack memory and return the memory
allocation roving pointer to the beginning, so the block allocated to
hold the name will be at the start of free memory and not in the
middle.
Avoid repetitive manipulation of strings with string values being
concatenated and substringed. Each such operation creates a new copy
91
Blinker Manual (c) 1990 Blink, Inc.
of the string and frees the old one. It is this creation and release
of tiny blocks of memory which tends to fragment memory into tiny
unuseable pieces as time goes on.
For Clipper Summer '87 the fragmentation display function BLIDISFRG ()
and the memory packing function BLIMEMPAK () help to monitor and
minimise fragmentation. Please also remember that the MEMORY (0)
function itself packs memory so if you want to measure the effect of
BLIMEMPAK () first run a routine for a number of iterations followed
by a MEMORY (0). Next include BLIMEMPAK () and run the routine for the
same number of iterations before doing a MEMORY (0), ensuring that the
number of iterations is sufficient to ensure that a BLIMEMPAK actually
occurs. The difference in the MEMORY (0) figures returned will
indicate the memory saving.
9.6 Use the BLINKER Profiler
_____________________________
For maximum memory savings it is desirable to overlay as much of your
code as possible. With Clipper compiled code this can be achieved by
compiling all the code into a single .OBJ placed between the BEGINAREA
and ENDAREA commands and having a one line calling procedure in the
root. However, for optimum application performance, it may be
necessary to extract from the overlay area any code which is called
continuously e.g. screen updating functions called many times a second
at run time.
Blinker provides a profiling utility which helps you identify the most
commonly called functions and procedures. This can also be a powerful
development analysis tool, enabling identification of the 20% of code
which is often doing 80% of the work. You can direct your optimisation
efforts to the code used most often to make maximum performance
improvements with minimum effort. The source code to the Clipper
profiler is included on the program diskette, so if it does not tell
you what you need to know, you can alter it.
Chapter 10 - Using the BLINKER Profiler - covers the use of the
profiler in more detail.
9.7 Enhance the BLINKER Error Handler
______________________________________
The source for the BLINKER error handler is provided on the
distribution diskette in the files BLERRPRG.PRG (for Summer '87) and
BLERRC50.PRG (for Clipper 5.0).
92
Blinker Manual (c) 1990 Blink, Inc.
These files may be modified like the normal error handling functions
in the Clipper ERRORSYS and then linked in to the application with the
other Clipper OBJs.
93
Blinker Manual (c) 1990 Blink, Inc.
_________________________________________________________________________
| |
| |
_________________________________________________________________________
| |
10.1 Overview
_____________
BLINKER provides a range of features which enable developers to
quickly and easily make vast improvements in the way their
applications make use of memory. These savings can often mean the
difference between whether an application will run on a network or
only run stand-alone, if at all.
Another development tool BLINKER provides which can offer just as
great, if not greater, improvements in both performance and memory
usage is the BLINKER profiler. A profiler is a utility to gather
statistics about the routines in which a program spends its time
during execution. These statistics can then be analyzed to determine
how best to make the program run more efficiently.
This chapter details the setting up and use of the BLINKER profiler in
order to make further improvements in memory usage and performance.
Thanks are due to Fred Stangl, who wrote the profiling routines
discussed here and supplied on the distribution diskette, and donated
them to all BLINKER users.
10.2 Linking the profiler to an application
___________________________________________
The profiler itself is written totally in Clipper and complete source
is provided on the BLINKER distribution diskette in the file
PROFILER.PRG, should further statistics be required. The set up and
use of the profiler is covered in this chapter, but for a complete
understanding of the operation of the profiler please study the source
program and experiment with it.
The comment at the top of PROFILER.PRG contains a few lines of startup
code to be added to the main routine of the application. These lines
initialise the public variables needed by the profiler during
execution of the application. Add these lines to the top of the main
.PRG of the application with any adjustments required to the PARAMETER
statement to allow for parameters which are already used in the
application.
The program PROFILER.PRG can then be compiled separately and linked to
the application as an extra FILE statement in the root. It is also
necessary to add the DEBUG statement to the link script file to ensure
that profiling information is recorded. The profiler may be overlayed
94
Blinker Manual (c) 1990 Blink, Inc.
if necessary, but this will have an adverse effect on performance and
is hardly worthwhile as it will be called throughout the application.
The profiler consists of two functions, BLPRFPRG () and OVL_STAT ().
BLPRFPRG () is automatically called every time an overlaid function is
called during execution of the application, and OVL_STAT () is called
to display the results of the profiling. The automatic calling of
BLPRFPRG () is enabled by placing DEBUG in the link script file and
then passing the value .T. to the profiling mode function BLIPRFMOD ()
at the start of the program.
BLPRFPRG () makes use of a number of functions provided by the BLINKER
overlay manager to record statistics about each overlaid procedure or
function as it is called from within the application. These functions
are detailed in Chapter 7 - BLINKER Programming Functions - and
include the size of the procedure or function, the number of times it
has been called and the number of times it has been loaded from disk.
The first function used is BLICURNME () which returns the name of the
procedure about to be loaded, which is then stored in a temporary
variable. An array of procedure names is scanned to see if there is an
entry already defined for that procedure, and if not then a new entry
is added for it.
The other statistics are recorded in parallel arrays of integers for
convenience (Clipper Summer '87 does not support multi-dimensional
arrays) using the same subscript as for the name array. The available
dynamic memory is also checked and compared to the highest and lowest
value so far, and these values are adjusted if necessary.
OVL_STAT () can be called at any time, and by default in the program
supplied is assigned to a hot key of Alt P. This function displays the
various statistics which have been recorded during execution of the
application, and may be called from anywhere in the program. It may
also be altered to send the output to a file or to another destination
such as the printer if required.
It should be noted that profiling will always have an adverse effect
on the performance of an application due to the extra work being
performed. The majority of the time delay in this profiler is actually
spent executing the MEMORY (0) call, so if minimum inteference is
required then the lines calling MEMORY (0) may be commented out, or
replaced with a call to BLIMEMBLK ().
10.3 Interpreting the results of the profiler
_____________________________________________
95
Blinker Manual (c) 1990 Blink, Inc.
When OVL_STAT is called up it displays a summary screen with various
statistics about the application currently running, and the
significance of each is discussed below:
Highest Free Pool Memory: This is the largest amount of dynamic memory
that was ever available to the application. (For most applications
this will be the amount of memory which was available at startup).
Monitoring this value during development and after making changes to
the application will indicate whether modifications have increased or
decreased the amount of memory available in the free pool.
Current Free Pool Memory: This is the amount of dynamic memory
currently available to the application as returned by MEMORY (0). If
this figure approaches zero then there is a possibility that the
application may fail with an out of memory error at this point in the
program.
Lowest Free Pool Memory: This is the lowest amount of dynamic memory
that was ever available to the application during its execution. This
is the figure to watch because if it ever goes below around 20 Kb then
Clipper could potentially run out of memory in a memory intensive
situation. It is advisable to attempt to make more memory available by
overlaying more code or combining Clipper .OBJs because after
prolonged use the application could use up this remaining memory.
BLINKER Memory Pack Frequency: This is the packing frequency as set by
the BLINKER MEMORY PACK
BLINKER Overlay Pool OpSize: This is the operating size of the overlay
pool as set by the BLINKER OVERLAY OPSIZE
script file. This represents the maximum amount of memory BLINKER will
allocate from Clipper for overlays before discarding unused overlays
to make more memory before loading the next overlay. To determine the
minimum setting for the OPSIZE, set it to a small value such as 10 KB,
run through all the options of the application WITHOUT performing a
BLIOVLCLR () and then check the value of BLIOVLOPS () just before
exit. This value will be the minimum value for the OPSIZE.
Current Overlay Pool Size: This is the amount of memory currently used
by BLINKER for overlays, and may vary from zero up to the Overlay Pool
OpSize, depending on how many overlays are currently in memory.
Total Proc Size Since Startup: This is the total size of all the
overlays loaded since the program started execution, and may be any
size up to the combined size of the overlay files. This is the total
amount of code which it has been possible to run within the amount of
memory given by the Overlay Pool OpSize above.
96
Blinker Manual (c) 1990 Blink, Inc.
Total Procedures Loaded: This is the total number of overlaid
procedures (active and inactive) currently loaded in the overlay pool
at that point in the program.
Procedures Currently Active: This is the total number of overlaid
procedures currently executing at that point in the program. The
difference between this number and the Total Procedures Loaded gives
the number of overlaid procedures which would be discarded on
performing a BLIOVLCLR ().
Total Calls Since Startup: This is the total number of overlaid
procedure calls since the program started execution.
Total Procedures Loaded: This is the total number of overlaid
procedure calls which have had to be loaded from disk since the
program started execution.
% Serviced From Overlay Pool: This percentage represents the
proportion of overlaid procedure calls which were found to already be
in memory, rather than having to reload them from disk. The higher
this percentage is the better the performance of the application as
the less the overlay manager has had to go to disk to reload the
procedure.
Pressing F2 at the summary screen displays a list of all the overlaid
procedures in the application and their individual results as stored
in the public arrays. Individual procedures can then be picked out
from this list and their performance assessed.
Pressing F3 at the summary screen displays a list of all the overlaid
procedures with a bar chart indicating the relative number of calls
made to each procedure. Pressing F3 while on this screen will toggle
the order of the list between natural mode, i.e. the order in which
the procedures were first called, and descending frequency of calls,
which will show the most called procedures down to the least called
procedures.
These detail screens may be used to identify at least two key areas
for attention, and probably many more.
The first area for attention is the % Service figures for each
procedure. If the figure for a particular procedure is low then it
means that it is often being loaded from disk, which may be
significantly slowing down the application if the procedure is called
many times. Therefore, if the procedure has a high call rate or is
used throughout the application then it is a candidate for placing in
the root to ensure that it is always available in memory.
97
Blinker Manual (c) 1990 Blink, Inc.
The second area for attention is the frequency of calls of each
procedure. If a procedure is called many times then it is obviously a
candidate for placing in the root, but it is also a candidate for
optimization to improve its execution speed. It is often said that 80%
of the execution time of an application is spent in 20% of the code,
and the calls bar chart allows you to identify that crucial 20%.
Like many things, the issues discussed here are often a compromise,
since there are usually two factors to be weighed up against one
another, e.g. memory against performance, elegance of algorithm
against clarity of code etc.
With a small amount of effort and time the profiler presented here can
go a long way to help you make the decisions required for each
application to get the best combination of performance, elegance and
functionality.
98
Blinker Manual (c) 1990 Blink, Inc.
_________________________________________________________________________
| |
11. The Future
| |
_________________________________________________________________________
| |
11.1 Overview
______________
Blink Inc. is committed to expanding and enhancing its product range
on a continuing basis, with an aggressive pricing policy for both the
complete products and upgrades for existing users.
Any suggestions for enhancements and / or new features will be
gratefully received, and will be prioritized for inclusion as soon as
the development cycle permits.
The following sections detail the major enhancements planned for the
next six to twelve months.
11.2 Swapping Out of Memory to Disk
___________________________________
A function BLIMEMSWP () will be introduced to allow the application to
free up as much memory as possible to run an external program. The
memory will be restored on return from the external program and
execution will continue without having to reinitialize everything.
11.3 Expanded / Extended Memory
_______________________________
Use of expanded and/or extended memory will be introduced, both by the
linker to decrease the application link time, and by the overlay
manager at application run time to store overlays rather than
discarding them and having to re-load them from disk.
11.4 Compression of Clipper's symbol table
__________________________________________
Currently symbols referenced in more than one .Clipper OBJ file are
duplicated in the final .EXE symbol table. A mechanism to remove all
the duplicate symbols will be provided, thus greatly reducing the size
of the symbol table in the final .EXE, which will reduce the memory
requirement of that .EXE accordingly.
11.5 Multiple Language Support
_______________________________
99
Blinker Manual (c) 1990 Blink, Inc.
BLINKER will support multiple languages in a standalone mode, i.e.
will be able to link and dynamically overlay applications written in
other languages, such as Microsoft and Turbo C and ASM.
11.6 Run Time Libraries
_______________________
BLINKER will be able to create pre-linked libraries to use with
multiple applications without having to link them into each
application .EXE file. Instead, they will be linked to the .EXE file
at run time when the .EXE is loaded by DOS. This will save significant
amounts of disk space as well as providing a convenient way of
maintaining a standard library of functions across many applications.
100
Blinker Manual (c) 1990 Blink, Inc.
_________________________________________________________________________
| |
12. Error Messages
| |
_________________________________________________________________________
| |
12.1 Overview
______________
The following sections contain a complete list of the BLINKER error
messages with a description of the reason for the error and the way to
avoid it.
The errors are divided into three classes, link time warning messages
of the form 10xx, link time fatal messages of the form 11xx and run
time messages of the form 12xx.
Link time warning messages are for information only and do not set the
DOS ERRORLEVEL, thus the execution of BLINKER and any MAKE utilities
being used will continue unaffected. They may be disabled altogether
using the BLINKER MESSAGE NOWARNING command detailed in section 6.20.
Link time fatal messages and run time messages, on the other hand, are
of a more serious nature. They cause immediate termination of the
program executing and set the DOS ERRORLEVEL to 1.
12.2 Link Time Warning Messages
________________________________
1001: invalid command parameter in '......' ignored
This message indicates that the command shown has been included with
an invalid parameter value.
See Chapter 6, BLINKER Script Commands for details of the parameters
required by the command displayed.
1002: duplicate input file '......' ignored
This message indicates that the same input file name appeared in more
than one FILE or LIBRARY command. The duplicated input file will be
ignored.
1003: no stack segment in EXE file
This message indicates that the application EXE file was created
without a stack segment, which would almost certainly cause the
application to fail at run time.
101
Blinker Manual (c) 1990 Blink, Inc.
The reason for this is almost certain to be the attempt to link
without a Clipper compiled program as the first FILE in the script
file, which is not supported in this version..
1004: (aaaaaa) 'bbbbbb' is duplicated in cccccc(dddddd)
This message indicates that the symbol bbbbbb defined as public in
module aaaaaa is also defined as public in module dddddd of file
cccccc.
This will occur if two procedures in separate OBJ or LIB files have
the same name, and the first one found is the one which will be linked
in to the application. The developer should avoid creating duplicate
procedures if at all possible to save confusion.
1005: aaaaaa: library has no cross reference record
This message is purely for information, and indicates that the
specified library was created with an old version of Microsoft LIB or
its equivalent. Newer versions of Microsoft LIB create a library cross
reference record which significantly reduces the time required to link
the library. For more information see section 6.34 SEARCH.
1006: aaaaaa: padding truncated to fit within 64Kb
This message is a warning that a procedure in the named file has a
size close enough to the 64kb limit to mean that there is not enough
space to add the full padding for incremental linking.
BLINKER automatically truncates the padding to ensure that the 64 kb
is not exceeded, but it is more efficient for overlaying and good
programming practice to keep procedure size down, typically to a few
hundred lines.
1007: unable to perform an incremental link
This message indicates that the attempted incremental link failed, and
that a full link will be performed to recreate the application .EXE
and associated incremental link file.
This can occur for a number of reasons, the usual ones being that a
new procedure or function has been added to one of the .OBJ files, the
order of files in the link script file has been changed or that the
application is being linked with a different link script file to the
previous one.
1008: aaaaaa: invalid incremental link file
102
Blinker Manual (c) 1990 Blink, Inc.
This message indicates that a previous incremental link was aborted
unsuccessfully and left an invalid incremental link file, or that the
file specified with the BLINKER INCREMENTAL FILE
valid incremental link file for the application concerned.
A full link will be performed to recreate the application .EXE and its
associated incremental link file.
1009: aaaaaa: file cannot be linked incrementally
This message indicates that while attempting to incrementally link the
application BLINKER found that a non-Clipper file had changed, and
incremental linking of non-Clipper files is not yet supported.
A full link will be performed to recreate the application .EXE and its
associated incremental link file.
1010: aaaaaa: no space available for incremental link
This message indicates that the named file has become too large to fit
in the space reserved for it when the last full link was performed.
A full link will be performed to recreate the application .EXE and its
associated incremental link file.
If you receive this message on a regular basis you may wish to increse
the space left for incremental linking by using the BLINKER
INCREMENTAL PAD
the padsize will increase the size of the .EXE and its memory
requirements during development, so remember to set incremental
linking off using the BLINKER INCREMENTAL OFF command detailed in
section 6.16 before distributing the application .EXE.
11.3 Link Time Fatal Messages
______________________________
1101: terminated by user
This message indicates that the user interrupted BLINKER while it was
running by pressing the Ctrl-C or Ctrl-Break keys.
1102: no input files were specified
This message indicates that no FILE commands were found on the BLINKER
command line or in any of the script files specified on the command
line.
103
Blinker Manual (c) 1990 Blink, Inc.
BLINKER requires at least one FILE command to indicate which object
file(s) are to be linked.
1103: input command '......' is invalid
This message indicates that the command shown is not a valid BLINKER
command.
See Chapter 6, BLINKER Script Commands for details of the valid
BLINKER commands and how to use them.
1104: unbalanced BEGINAREAs and ENDAREAs
This message indicates that a different number of BEGINAREA and
ENDAREA commands were found on the command line or in the script file,
which implies an invalid overlay structure. See Chapter 6, BLINKER
Script Commands for a complete description of the BEGINAREA and
ENDAREA commands.
1105: script files cannot be nested
This message indicates that a script file name (@aaaaaa) was found
inside another script file, and BLINKER does not support nested script
files.
It may be possible to alleviate the problem by splitting the script
files into two or more files specified one after the other on the
BLINKER command line. For example,
BLINKER @script1 @script2
1106: not enough memory to continue processing
This message indicates that there is not enough memory available from
DOS to continue building the tables required by BLINKER. BLINKER
requires a minimum of 256KB of free memory to run reasonably quickly.
To make more memory available either remove one or more TSRs currently
resident, run BLINKER from outside a make utility or reduce the number
of buffers specified in the CONFIG.SYS
1107: disk full writing output file
This message indicates that the destination disk is full, there was an
error writing to the disk, you do not have write access to the output
path specified, or the output file name is invalid.
104
Blinker Manual (c) 1990 Blink, Inc.
If there is plenty of space available then this message indicates that
there may be a problem writing to the disk, which can be checked by
attempting to copy some other files to the destination disk and path.
1108: unable to find file aaaaaa in the appropriate path
This message indicates that BLINKER was unable to find the specified
file in the current directory or the appropriate path, depending on
the extension of the file.
If the file is an OBJ file check the OBJ environment variable, if it
is a LIB file check the LIB environment variable or if it is another
type of file check the PATH environment variable. When running on a
network it is also possible that another user deleted the file or you
do not have network access rights to the file.
1109: unable to open file aaaaaa
This message indicates that BLINKER was unable to find or create the
specified file in the current directory where it was expected to be,
so the full directory path for the file should be specified. If no
file extension is specified for script files BLINKER assumes an
extension of .LNK.
1110: aaaaaa: invalid object file
This message indicates that the file shown, which may be an OBJ file
or a LIB file, contains an invalid object record.
If the file is expected to be valid then it has probably become
corrupt. To rectify this either recreate the file by recompiling or
reinstall the appropriate file from the installation diskette.
1111: aaaaaa: invalid segment definition
The same information applies as for error message number 1110.
1112: aaaaaa: invalid group definition
The same information applies as for error message number 1110.
1113: aaaaaa: segment exceeds 64KB
This message indicates one of a number of situations.
The usual cause of this problem is that the first .OBJ file specifed
on the command line or in the script file is not a Clipper .OBJ file.
105
Blinker Manual (c) 1990 Blink, Inc.
In this version of BLINKER the first .OBJ file specified must be a
Clipper .OBJ file.
Secondly, two related libraries may have been separated by other
libraries in the link script file, so that the code in one library
cannot reach the code in the other library. This may also occur when
multiple .OBJs extracted from the same library or that are related
have been separated by too many other .OBJ files in the script file.
Thirdly, two libraries may have declared the same segment names in
different classes, which should not occur in most applications.
Lastly, this may occur if a procedure has the same name as certain
reserved words - the main ones are _BSS, _DATA, DATA, DGROUP and MSG.
If the first .OBJ file is definitely a Clipper .OBJ then please review
Chapter 4 - Setting Up a Link Script File which discusses the order of
3rd party libraries in the script file. Also check that any libraries
being overlaid are definitely overlayable - please refer to the chart
3RDPARTY supplied on the distribution diskette.
If none of these work and recreating or reinstalling the specified
file does not help then please contact BLINKER technical support with
exact details of the problem.
1114: (aaaaaa) 'bbbbbb' is duplicated in cccccc(dddddd)
The same information applies as for warning error message number 1004,
only because of the nature of the duplication linking cannot continue.
To resolve this error one of the procedures must be given a different
name and the appropriate .OBJ file recompiled.
1115: aaaaaa(bbbbbb) 'cccccc': unresolved external
This message indicates that the symbol cccccc defined as external in
module bbbbbb of file aaaaaa cannot be found declared as public in any
of the other .OBJ files or libraries in the script file.
The usual cause of this problem is that an object or library file
required by the application has been omitted from the script file. If
not, this can usually be resolved by checking the order of the
libraries to ensure that the library containing the missing external
'cccccc' comes after the module aaaaaa(bbbbbb) which is calling it.
Another possible cause of this message is that some libraries require
the use of the SEARCH command as their library cross reference records
are not complete. For a full description of the SEARCH command and
library cross-reference records see section 6.34 - SEARCH.
106
Blinker Manual (c) 1990 Blink, Inc.
If you get '__dos_hold' as an unresolved external then please check
you have the updated version of CLIPPER.EXE, CLIPPER.LIB and
EXTEND.LIB from Nantucket. The original versions all have a date of
12-21-87 and a time of 12:00 am (which may not be displayed), while
the updated versions have the same date but a time of 2:00am. BLINKER
wil only work correctly with the updated versions as there were a
number of problems fixed in them.
1116: aaaaaa(bbbbbb) fix up overflow, frame=0000h target=0000h
offset=0000h
The same information applies as for error message number 1113.
1117: aaaaaa: invalid library cross reference record
This message indicates that the specified library contains a cross
reference record but its format is invalid. This usually indicates
that the library file has become corrupt and should be recreated or
reinstalled.
For a full description of the SEARCH command and library cross-
reference records see section 6.34 - SEARCH.
1118: too many external overlays
This message indicates that more than 15 unique external overlay file
names were specified in the link script file. This version of BLINKER
only supports up to 15 external overlays. It should be noted that with
BLINKER the only reason to have more than 1 external overlay file is
so that each overlay file will fit onto a 360 Kb diskette.
For a full description of external overlays see section 6.36 - SECTION
INTO.
1119: no main module found
This message indicates that no start up procedure was found in the
files and libraries to be linked. This usually happens when
CLIPPER.LIB is omitted from the script file or a non-Clipper OBJ file
is the only input file specified.
1120: incremental link file is too large
This message indicates that the incremental link file created by
BLINKER has exceeded the maximum allowable size. If you receive this
message please contact BLINKER technical support with exact details of
the circumstances causing the error.
107
Blinker Manual (c) 1990 Blink, Inc.
1180: too many entries in file table
1181: too many entries in LNAMEs table
1182: too many entries in map table
1183: too many entries in symbol names table
1184: too many entries in communals table
1185: too many modules in library table
1186: too many fixups in overlay
All these messages indicate reaching the BLINKER internal size limit
of the specified table. If you receive one of these messages please
contact BLINKER technical support with exact details of the
circumstances causing the error.
1189: EXE file is corrupt
This error message should not occur in normal operation, but it
indicates that the BLINKER.EXE file has become corrupt and should be
reinstalled from the distribution disk.
1190: internal error - invalid symbol number
1191: internal error - invalid buffer number
1192: internal error - invalid page number
1193: internal error - invalid word offset
1194: internal error - invalid module number
1195: internal error - invalid public number
1196: internal error - invalid external number
1197: internal error - invalid group number
1198: internal error - invalid segment number
1199: internal error - DOS function call error
None of these error message should occur in normal operation. If one
of these messages is displayed then please contact BLINKER technical
support with exact details of the circumstances causing the error.
108
Blinker Manual (c) 1990 Blink, Inc.
12.4 Run Time Error Messages
_____________________________
These error numbers are passed to the Clipper error handler BLERRPRG
which is supplied on the BLINKER diskette in the file BLERRPRG.PRG
(for Clipper Summer '87) or BLERRC50.PRG (for Clipper 5.0). By default
a compiled version of this error handler is linked in to all
applications. See Chapter 8, Creating Demonstration Versions for more
details on the error handler.
It is recommended that if the BLERRPRG procedure is to be changed then
it should be included in the developer's ERRORSYS.PRG file where it
may be modified to suit the developer's method of handling errors.
1201: unable to find overlay file aaaaaa in the current PATH
This message indicates that either too many files are open or that the
external overlay file aaaaaa, specified and created at link time, can
no longer be found in the current directory or the current PATH.
Ensure that the CONFIG.SYS file and the CLIPPER environment variable
provide sufficient file handles to allow an extra one for the overlay
manager. Ensure also that the overlay file name specified is available
in the current directory or in the PATH environment variable.
1202: DOS read error in file aaaaaa
This message indicates that DOS returned an error while moving to a
particular position in the overlay file or while reading the required
overlay from the file.
This error usually occurs when a function to set the maximum number of
file handles DOS may open is called after BLINKER has opened the
overlay file and loaded one or more overlays from the file. The reason
for this is that the functions create a new table of file handles
which invalidate the file handle given to BLINKER for its overlay
file. To avoid this, ensure that the handles function is called from
the root before BLINKER has loaded any overlays.
Do not call one of these handle increasing routines such as FUNCKY's
SETHANDLES (n) from an overlay with versions of DOS >= 3.3 at the same
time as the CLIPPER Fn parameter since the combination causes a
BLINKER 1202 error because the overlay file gets closed !! Always
check the DOS version i.e. use:
IF DOSVERSION () < 3.3
SETHANDLES (29)
109
Blinker Manual (c) 1990 Blink, Inc.
ENDIF
This error can also occur when certain C or Assembler code which is
not overlayable has been placed in the overlay area. If there are any
non-Clipper .OBJs or .LIBs in the overlay area which are not known to
be overlayable then these should be moved to the root and the
application relinked.
If the application then runs successfully this indicates that the
file(s) are not currently overlayable (see the file 3RDPARTY on the
distribution diskette for an up to date list of libraries which are
known to be overlayable, or call our Technical Support BBS on (804)
355-1111 to download the latest version of 3RDPARTY.
Finally, this error can occur when the overlay file has been closed by
an external influence such as a TSR or being logged off a network,
which the current BLINKER overlay manager has no way of detecting and
handling, or when the overlay file has become corrupt because of a
disk error and should be reinstalled.
1203: file aaaaaa is not a valid EXE file
This message indicates that the specified file does not have a valid
EXE file header, thus the BLINKER internal overlay cannot be located
within the file. This indicates that the file has become overwritten
by another file, that the PATH has changed so that an alternative file
of the same name is found instead, or that the EXE file has become
corrupt.
1204: overlay file aaaaaa does not match the EXE file
This message indicates that when the overlay manager opened the
overlay file specified and created at link time, it was not a BLINKER
overlay file or it was not prepared at the same time as the currently
executing EXE file.
This indicates that the correct copy of the overlay file has become
overwritten by an older version, the newer version cannot be found in
the current PATH, or the previous link was terminated before the
overlay file was created correctly.
1205: not enough memory to load procedure
This message indicates that there is no more dynamic memory available
from Clipper to load the requested overlay procedure.
110
Blinker Manual (c) 1990 Blink, Inc.
For a description of how to maximize the amount of dynamic memory
available to Clipper please refer to sections 5.3 and 5.4 of this
manual.
1206: maximum procedure nesting depth exceeded
This message indicates that during execution of the application the
depth of nested procedures, i.e. the number of procedures calling one
another without returning, has exceeded the maximum that may be
handled on the procedure call stack.
To increase the size of the procedure call stack simply add a BLINKER
PROCEDURE DEPTH
PROCEDURE DEPTH).
1207: demonstration calls limit exceeded
This message indicates that the application was linked with the
BLINKER DEMONSTRATION CALLS
program with a limited number of procedure calls, and that limit has
now been reached. For more details on demonstration versions see
Chapter 8, Creating Demonstration Versions.
1208: demonstration date limit exceeded
This message indicates that the application was linked with the
BLINKER DEMONSTRATION DATE
program with an expiration date, and that date has now been exceeded.
For more details on demonstration versions see Chapter 8, Creating
Demonstration Versions.
1209: demonstration time limit exceeded
This message indicates that the application was linked with the
BLINKER DEMONSTRATION MINUTES
demonstration program with a limited execution time, and that limit
has now been reached. For more details on demonstration versions see
Chapter 8, Creating Demonstration Versions.
1210: overlay has been prematurely freed
This message indicates that the memory assigned to an overlay has been
prematurely freed by Clipper's memory management routines. The BLINKER
overlay manager checks for this whenever it manipulates dynamic
memory.
111
Blinker Manual (c) 1990 Blink, Inc.
12.5 Other Common Errors
_________________________
Application exhibits erratic hanging / strange results
Check if the 2nd line of the screen (line 1) is being cleared - this
is a clear indication that the BLINKER error handler BLERRPRG is being
called. Check if the ERRORSYS program, or anything that it calls, is
being overlaid, and if it is move it back into the root until the
source of the error is found in case it is an overlay file error.
Stack overflow may cause erratic results such as undefined variables,
type mismatches, out of memory while MEMORY (0) still says memory
available, sometimes hanging etc. even though BLINKER attempts to
check this and report if the stack has overflowed.
Increase BLINKER PROCEDURE DEPTH - the default is 20 - try increasing
it in increments of 5 or 10 - 50 should be plenty for most
applications. (Each 10 represents approximately 1 Kb of stack space).
Note: FUNCky, NETLIB and GETIT make heavy use of the stack, as does
Novell NetWare, so watch out if networks are involved - A PROCEDURE
DEPTH of 50 is recommended in these cases.
Check for a STACK command from an old PLINK86plus script file -
PLINK86plus defaults to HEXADECIMAL for the value, thus STACK 1000
means a 4KB stack, whereas BLINKER defaults to DECIMAL and this would
be a 1KB stack. When BLINKER PROCEDURE DEPTH and STACK are used, the
last one in the script file is the one that has effect.
Corrupt indexes
Indications of corrupt indexes include DOS error 0 and internal error
92. Ensure that the Clipper E parameter is set to 0 and R is
sufficient - We have found 16 sufficient for small applications and
database files of up to 10,000 records, and 32 for large applications
and database files with greater than 10,000 records.
DOS error 4
This error is from DOS and indicates that there are no more handles
left to open another file. Check that the CONFIG.SYS contains a
FILES=nn line with at least as many as the number set in Clipper's F
parameter, and that the Clipper F parameter is set to a sufficient
number for the application.
Remember that BLINKER requires one file handle per overlay, i.e. one
for an internal overlay or one per SECTION INTO command.
Run error
112
Blinker Manual (c) 1990 Blink, Inc.
This error occurs when a Clipper program attempts to RUN another
program from inside itself. The most common causes of this error are
not setting the E and R values for the CLIPPER environment variable. E
should be set to 0 and R should be set to a minimum of 16, and should
leave room for the DOS command processor and the program to be RUN.
RUN commands can also fail if DOS has no more handles available as it
appears to need a handle to load COMMAND.COM.
Sharing Violation
Certain networks including 3COM and LANTASTIC are giving a SHARING
VIOLATION with INTERNAL overlays when a second copy of the application
is loaded. This appears to be due to the network requiring exclusive
write access to the file when it loads it.
To get around this problem if it occurs either reprotect the .EXE to
READ ONLY access using ATTRIB.EXE or an equivalent, or use an external
overlay by specifying SECTION INTO at the start of the BEGINAREA in
the script file.
113
Blinker Manual (c) 1990 Blink, Inc.
_________________________________________________________________________
| |
Glossary
| |
_________________________________________________________________________
| |
ASCII: American Standard Code for Information Interchange - the almost
world wide standard for representing characters in the memory of a
computer.
Byte: Eight bits of data, the smallest unit of information stored in
the computer's memory. One byte is required to store one ASCII
character. (See also: ASCII)
Class: A collection of segments which are to be associated in memory.
Classes are usually compiler specified, and are used to place segments
within a general area of memory. Segments are placed within a class in
the order they are encountered in processing .OBJ files. (See also:
.OBJ File, Segment)
Compiling: The process of translating source code into object code in
.OBJ files. The resulting object code can then be linked to produce an
executable program. (See also: Linking, .OBJ File, Source Code)
Dynamic memory: The area of memory used by Clipper to store the values
of variables used in a Clipper application. This memory is also used
by Clipper for temporary buffers for internal processing such as file
and index buffers. The Clipper function MEMORY (0) returns the size in
KB of the dynamic memory during program execution.
Dynamic Overlaying: The process of loading , executing and discarding
overlays at application run time on demand, rather than according to a
predefined overlay structure. (See also: Overlay, Static Overlaying)
.EXE file: An executable program file which is the output from a
successful link. This file may contain the complete program or it may
have associated files to contain the remainder of the program. In all
cases it is the file executed by DOS when the program name is typed at
the DOS prompt.
External Overlay: A file separate from but related to the application
.EXE file, containing one or more overlays to be loaded and executed
when required. (See also: .EXE file, Overlay)
Free Pool: See Dynamic Memory
Incremental linking: The process of linking only the parts of an
application program which have changed since the previous link. This
process can greatly speed up the time required to link the application
during development. (See also: Linking)
114
Blinker Manual (c) 1990 Blink, Inc.
Internal Overlay: The part of an .EXE file containing the overlays
associated with the main program .EXE, attached to the end of it for
convenience.
.LIB file: A library file containing one or more .OBJ files for
convenience. When a library file is linked with an application only
those .OBJ files which are required from the library are pulled out of
the library and used. (See also: Linking, .OBJ file)
Linking: The process of combining .OBJ files, searching library files
for additional .OBJ files, resolving references between these .OBJ
files and producing an executable program .EXE file. (See also: .EXE
file, .LIB file, .OBJ file)
Module: A module is equivalent to an .OBJ file, usually within a .LIB
file, and the module name usually corresponds to the name of the
source file from which the .OBJ was created. (See also: .LIB file,
Source Code)
.OBJ file: An object file containing code produced by some sort of
language translator. The file consists of program code, data to be
used by the program and symbolic information which tells the linker
how to combine this file with other .OBJ files to produce an .EXE
file. (See also: .EXE file)
Overlay: A section of program code which is loaded into memory,
executed a number of times and then discarded to make room for another
section of code. The use of overlays enables programs larger than the
amount of available memory to run successfully.
Overlay Manager: A section of code which manages the loading,
execution and discarding of overlays while an application program is
running. This code is responsible for ensuring that all the required
overlays of an application are in memory when they are needed and
doing so as efficiently as possible. (See also: Overlay)
Overlay Pool: The area of memory in which overlays currently in memory
are stored. This area is controlled by the overlay manager while the
program is running and is taken from Clipper's dynamic memory by
BLINKER as and when required. (See also: Dynamic Memory, Overlay
Manager)
Profiling: The process of gathering statistics about the routines in
which a program spends its time during execution. These statistics can
then be analyzed to determine how to make the program run more
efficiently.
115
Blinker Manual (c) 1990 Blink, Inc.
Root: The section of an application program which always remains in
memory and is never overlaid. DOS will always load at least this
section into memory, while other sections or overlays may be loaded by
the overlay manager as and when required. (See also: Overlay, Overlay
Manager)
Segment: A block of memory consisting of up to 64 Kb of code or data.
With BLINKER, segments are the basic units of overlaying, i.e each
overlay consists of a segment from an .OBJ file. (See also: .OBJ File,
Overlay)
Source Code: The program code as written out and entered into the
computer by the programmer. It would be written in one of the many
programming languages such as dBase, Clipper, C or Assembler.
Static Overlaying: The process of loading , executing and discarding
overlays at application run time according to a predefined overlay
structure set up by the linker and determined by the developer in the
link script file. (See also: Dynamic Overlaying, Overlay)
Unresolved External: A named routine or piece of data which was
referenced by one or more of the .OBJ files being linked which was not
found in any of the .OBJ or .LIB files being linked. Unresolved
externals usually mean that one or more necessary .OBJ or .LIB files
have been omitted from the link process. (See also: .LIB File, .OBJ
File)
116
Blinker Manual (c) 1990 Blink, Inc.
_________________________________________________________________________
| |
Index
| |
_________________________________________________________________________
| |
ALLOCATE
AUTOEXEC.BAT
BATCH
BEGINAREA
BLERRPRG
BLICURCAL
BLICURDSK
BLICURNME
BLICURSIZ
BLIDBGHAN
BLIDEMCAL
BLIDEMDTE
BLIDEMMIN
BLIDISFRG
BLIDISOVL
BLIDISSTS
BLIDISTRC
BLIERRNUM
BLIERRPRM
BLILSTFRG
BLIMEMAVL
BLIMEMBLK
BLIMEMMAX
BLIMEMPAK
BLIMEMSIZ
BLIMEMUSE
BLINKER
error number
error parameter
BLINKER commands
DEBUG HANDLE
DEMONSTRATION CALLS
DEMONSTRATION DATE
DEMONSTRATION MINUTES
ENVIRONMENT NAME
ENVIRONMENT OVERRIDE
EXECUTABLE CLIPPER
EXECUTABLE SERIAL
INCREMENTAL FILE
INCREMENTAL OFF
INCREMENTAL PAD
MEMORY PACK
MESSAGE NOBLINK
MESSAGE NOWARNING
117
Blinker Manual (c) 1990 Blink, Inc.
MESSAGE WINK
OVERLAY OPSIZE
PROCEDURE DEPTH
BLIOVLCLR
BLIOVLOPS
BLIOVLSIZ
BLIPRFMOD
BLISERNUM
BLISTRFRG
BLITOTACT
BLITOTCAL
BLITOTDSK
BLITOTLOD
BLITOTSIZ
Clear inactive overlays
COMMAND.COM
Currentúprocedureúcalls
Currentúprocedureúdiskúloads
Currentúprocedureúname
Currentúprocedureúsize
DEBUG
Debug handle
Demonstration versions
Displayúallúoverlays
Displayúcallútrace
Displayúfragmentation
Displayúoverlayústatus
ENDAREA
Environment
CLIPPER variable
LIB variable
OBJ variable
PATH variable
setting up
Error messages
FILE
Fragmentation
FUNCky
HEIGHT
Installation
LIBRARY
118
Blinker Manual (c) 1990 Blink, Inc.
List fragmentation
LOWERCASE
MAP
Maximum memory block size
Memory available in blocks
Memory packing frequency
NOBELL
OUTPUT
OVERLAY
Overlay pool
current size
operating size
OVERLAY.LIB
Overlays,
dynamic
traditional
Overview
Profiling mode
RAM disk
Script commands
# (comment)
ALLOCATE
BEGINAREA
DEBUG
ENDAREA
FILE
HEIGHT
LIBRARY
LOWERCASE
MAP
NOBELL
OUTPUT
OVERLAY
SEARCH
SECTION
SECTIONúINTO
STACK
UPPERCASE
VERBOSE
WIDTH
WORKFILE
SEARCH
119
Blinker Manual (c) 1990 Blink, Inc.
SECTION
SECTION INTO
Serial Number
SHELL
STACK
String of fragmentation
Symbol table
System requirements
Thanks
Total active procedures
Total loaded procedures
Total memory available
Total memory size
Total memory used
Total procedure calls
Total procedure disk loads
Total procedure size
Trademarks
UPPERCASE
VERBOSE
WIDTH
WORKFILE
120
Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!
This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.
But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/