3RDPARTY.EXE.........Integrating third-party libraries with dCLIP
DCLIP.LIB............The main dCLIP overlayable library
DCLIP3*.RT...........Creating a 5.01 custom dCLIP engine with Rtlink
DCLIP3.BL............Creating a Custom dCLIP engine with Blinker
DCLIP52.RT...........Creating a 5.2 Custom dCLIP Engine with RTLINK
DCLIPNL.LIB..........The dynamic-link library
DCLIPR.LIB...........The dCLIP root (non-overlayable) library
DCLIPS.LIB...........The dCLIP "stubs" library
LINKING..............Linking dCLIP functions into your applications
CONVENTIONS..........dCLIP Programming Conventions
3RDPARTY.EXE
Integrating third-party libraries with dCLIP
Description:
dCLIP supports compatability with all third-party products
designed for use with Clipper 5.01 and 5.2.
Many third-party products have been tested with dCLIP and
can be integrated with the dCLIP libraries or linked into a
dCLIP engine.
When using third-party products it is recommended that you
own a copy of Blinker version 1.5 or later for best results.
Link scripts for RTLINK are not provided due to the
complexity of handling all the overlaying problems with
Rtlink. A demonstration copy of Blinker is provided to
demonstrate how easy it is to use Blinker with dCLIP. Any
program linked with the demonstration version supports all
the features except the program will run for a limited time
and then abort.
Each third-party product is supported in a separate
link-script file and external list file(s). To include
functions from a third-party library in a dCLIP engine,
first locate the name of the product in the dCLIP.BL master
link-script and remove the comment marker (#) from in front
of the designated link-script to force the script to be
included.
3RDPARTY.EXE is a self-extracting file that contains
link-script files for all the popular third-party products
tested with dCLIP. To extract the files simply run the
3RDPARTY.EXE program.
For example, to include the NANFORUM Toolkit library in a
dCLIP engine, perform the following steps:
1. Change the code in dCLIP3.BL as follows:
WAS:
# --- Nanforum Toolkit Library (Public Domain) ------ # #
@DCLIPNAN.BL
IS:
# --- Nanforum Toolkit Library (Public Domain) ------ #
@DCLIPNAN.BL
2. Compile the program containing the external list for all
the functions you want linked into the dCLIP.EXE engine.
CLIPPER DCLIPNAN.prg /n/l
3. Make sure that the third-party and dCLIP libraries can be
found by including them in your SET LIB=(path) and SET
OBJ=(path) environment.
4. Create the dCLIP.EXE program as follows:
BLINKER @DCLIP3.BL
Notes:
3RDPARTY.EXE also contains a file named README.3RD which
contains the latest information about the third-party
products that have been tested with dCLIP.
Source/Library:
3RDPARTY.EXE
DCLIP.LIB
The main dCLIP overlayable library
Description:
DCLIP.LIB is the library that contains the dCLIP
functionality, less the dynamic-linking capability. This
library is completely overlayable and is compatabile with
any dynamic-overlaying linker. Approximately 95% of the
code in DCLIP.LIB is compiled in Clipper therefore, 95% will
automatically be dynamically overlayed when using Rtlink or
Blinker. The remaining 5% is written in C or ASM and is
overlayable only by including the library in a Blinker
BEGINAREA..ENDAREA or, if using Rtlink, the C/ASM modules
may be overlayed using the RELOAD, BEGINAREA..ENDAREA, and
MODULE commands. See the DCLIP3.BL and DCLIP3.RT link
script files for examples of how to overlay DCLIP.LIB.
Source/Library:
DCLIP.LIB
DCLIP3*.RT
Creating a 5.01 custom dCLIP engine with Rtlink
Description:
DCLIP3.RT is a link-script file for use with Rtlink and
Clipper version 5.01. DCLIP3A.RT is a link-script file for
use with Rtlink and Clipper version 5.01a.
These files contains all the Rtlink commands necessary for
creating a custom DCLIP.EXE program with your own Clipper
libraries or third-party libraries written mostly in
Clipper.
If you wish to link third-party database drivers and/or
other function libraries written in C or ASM, then it is
recommended that you use Blinker 1.5 or later. Overlaying
third-party libraries with Rtlink is too complicated to
support all the ramifications and combinations in any set of
link-script files, therefore you are on your own if you wish
to use third party libraries and want to create overlay
areas.
Source/Library:
DCLIP3.RT/DCLIP3A.RT
DCLIP3.BL
Creating a Custom dCLIP engine with Blinker
Description:
DCLIP3.BL is a link-script file for use with Blinker version
1.51 or later. This file contains all the Blinker commands
necessary for creating a custom DCLIP.EXE program with your
own libraries and/or third-party library functions.
Instructions for using DCLIP3.BL are included as comments
(#) in the file.
Many third-party products have been already tested with the
dCLIP libraries and are integrated by simply removing the
comment marker (#) hash-mark from the line of code that
includes the third-party link-script.
For example, to include the DBFSIX driver in a dCLIP engine,
remove the hash-mark from the line containing @DCLIPSIX.BL,
then extract the DCLIPSIX.BL link-script file from the
3RDPARTY.EXE file and create the new DCLIP.EXE as follows:
BLINKER @DCLIP3.BL
Source/Library:
DCLIP3.BL
DCLIP52.RT
Creating a 5.2 Custom dCLIP Engine with RTLINK
Description:
DCLIP52.RT is a link-script file for use with Rtlink and
Clipper version 5.2x.
This file contains all the Rtlink commands necessary for
creating a custom DCLIP.EXE program with your own Clipper
libraries or third-party libraries written mostly in
Clipper.
If you wish to link third-party database drivers and/or
other function libraries written in C or ASM, then it is
recommended that you use Blinker 1.5 or later. Overlaying
third-party libraries with Rtlink is too complicated to
support all the ramifications and combinations in any set of
link-script files, therefore you are on your own if you wish
to use third party libraries and want to create overlay
areas.
Source/Library:
DCLIP52.RT
DCLIPNL.LIB
The dynamic-link library
Description:
DCLIPNL.LIB contains the dCLIP "dynamic-linking" system and
functions. This library contains everything needed to
include dynamic-linking in your own applications without the
need for any other dCLIP libraries or third-party libraries.
Examples and instructions for adding dynamic-linking to your
application are included in DYNAMIC.PRG, DYNAMIC.BL,
DYNAMIC.RT.
The DCLIPNL.LIB dynamic-link library contains some modules
that are overlayable and others that are not, therefore it
is recommended that you include the command @DCLIPNL.BL in
your BLINKER link scripts or @DCLIPNL.RT in your RTLINK
link-scripts to include the link scripts for handling the
overlaying of the DCLIPNL.LIB modules.
Using the dCLIP dynamic-linking system in your applications
will add approximately 15k (Blinker) or 25k (Rtlink) of
overhead to your application "plus" the amount of memory you
reserve for the dynamic-link pool. The memory is reserved
by using the SET CLIPPER X parameter. This amount of memory
reserve may be "burned-in" to your application with the
BLINKER EXECUTABLE CLIPPER=X(memory) command. It is
recommended that you also use BLINKER ENVIRONMENT OVERRIDE
to allow the memory pool to be increased or decreased before
starting the application with the SET CLIPPER=X(memory)
environment variable.
Notes:
Dynamic linking cannot be used in protected mode. If you
link with the DCLIPNL.LIB library, the dynamic-link system
will not be initialized if your application starts up in
protected mode.
Source/Library:
DCLIPNL.LIB
DCLIPR.LIB
The dCLIP root (non-overlayable) library
Description:
DCLIPR.LIB contains C and ASM code that cannot be overlayed
because this code accesses debugging information and/or
services interrupts.
DCLIPR.LIB must be listed in your link-script files ahead of
the CLIPPER.LIB library for the dCLIP debugging features to
function properly.
Source/Library:
DCLIPR.LIB
DCLIPS.LIB
The dCLIP "stubs" library
Description:
DCLIPS.LIB is a library of "stub" functions. This library
must always be listed LAST in your link scripts and is used
to resolve "missing symbols" during linking. Many of
dCLIP's menus and functions support the capability of
dynamic-linking, third-party RDD's, etc. For example, if
the DBFSIX, DBFMDX, DBFCMX, or FLEXFILE-II driver are
linked into your application, the dCLIP command set and
menus will automatically include the features of the
RDD(s) linked in. If the respective drivers are NOT linked
into the application, then stub functions must be available
to insure that the application will link properly and will
return default null values to disable the associated
feature.
DCLIPS.LIB is completely overlayable, so it may be included
in a BEGINAREA..ENDAREA.
Notes:
The DCLIPS.LIB library is a "stubs" library. This library
is provided to make it unnecessary to create two versions of
the dCLIP libraries (5.01 vs 5.2). The dCLIP 3.00 libraries
are compatabile with Clipper 5.01 only, but the 3.01 and
later versions are compatible with both 5.01 and 5.2. The
DCLIPS.LIB library **--MUST ALWAYS BE LISTED LAST--** in
your link scripts otherwise your applications will not work
and may even lock up. This means that DCLIPS.LIB must even
be listed after CLIPPER.LIB. If you fail to list
CLIPPER.LIB in your link script then, by default, CLIPPER.LIB
is always linked last, even if DCLIPS.LIB is the last library
listed.
Source/Library:
DCLIPS.LIB
LINKING
Linking dCLIP functions into your applications
Description:
-- BLINKER --
The file named DCTEMPL.BL is a recommended template for
linking your application with the dCLIP libraries and
Blinker version 1.51 or later.
The basics for linking with Blinker are as follows:
# myapp.lnk
BEGINAREA
FILE (your Clipper-compiled .OBJs)
LIB (your overlayable libraries)
LIB dclip # dCLIP main overlayable library
ENDAREA
LIB (your non-overlayable libraries)
LIB dclipr # dCLIP root (non-overlayable library)
# @dclipnl.bl # overlay script for dynamic-linking
@ clmid520.lnk # overlay script for Clipper libraries
BEGINAREA
LIB dclips # dCLIP "stubs" library
ENDAREA
-- RTLINK --
The file named DCTEMPL.RT is a recommended template for
linking your application with the dCLIP libraries and
Rtlink.
The basics for linking with Rtlink are as follows:
# myapp.lnk
FILE (your Clipper-compiled .OBJs)
LIB (your libraries)
LIB dclip # dCLIP main overlayable library
LIB dclipr # dCLIP root (non-overlayable library)
# @dclipnl.rt # overlay script for dynamic-linking
LIB clipper
LIB dclips # dCLIP "stubs" library
CONVENTIONS
dCLIP Programming Conventions
Description:
dCLIP is written almost entirely in Clipper with the
exception of a few small routines written in .ASM such as
the mouse interrupt handler and primitives and others
written in C for purposes of speed performance such as
the command parser. In addition, most of the DCLIPNL.LIB
(dynamic-linking) system is written in C/ASM. The source
code is provided for all of dCLIP except for DCLIPNL.LIB.
LOCAL MEMORY VARIABLES
All functions use LOCAL memory variables for the purpose
of code encapsulation, speed and memory management. Local
variables and passed parameters all follow the "Hungarian
Notation" specification. Ex: cFileName, dStartDate,
nIncrement, aFields, etc. The first letter of each local
variable is the "type" of variable followed by a name for the
variable that documents its function. Only LOCAL variables
and arrays use both Upper and Lower case letters.
STATIC ARRAYS
All STATICS variables needed by any procedure or functions are
kept in an array rather than individual variables. This
reduces the DGROUP usage and improves the memory profile.
The static array elements are given Manifest Symbols by #define
statements in the source code per the following example.
STATIC aRecur := { ,,,, }
#define sdSTARTDATE aRecur[1]
#define sdENDDATE aRecur[2]
#define snMONTH aRecur[3]
#define snDAY aRecur[4]
#define scOCCURCODE aRecur[5]
#define slUPDATED aRecur[6]
A Static-array "Manifest Symbol" is characterized by a lower
case letter "s" followed by a lower case letter designating the
"type" of variable followed by all upper case letters
representing a name for the psuedo-symbol that describes its
function.
PRIVATE/PUBLIC ARRAYS
There are system values that need to be passed around through
modules in dCLIP which are kept in PUBLIC arrays.
The public array elements are given Manifest Symbols by #define
statements in DC*.CH definition files per the following example.
// Start Display Row of Browse Display
#define pnSTROW dCBROWSE[nBrowArea,1,1]
// Start Display Column of Browse Display
#define pnSTCOL dCBROWSE[nBrowArea,1,2]
// End Row of Browse Display
#define pnENROW dCBROWSE[nBrowArea,1,3]
// End Column of Browse Display
#define pnENCOL dCBROWSE[nBrowArea,1,4]
// First Field Displayed
#define pnSTARTCOL dCBROWSE[nBrowArea,1,5]
// Current record pointer
#define pnSAVEREC dCBROWSE[nBrowArea,1,6]
A Public-array "Manifest Symbol" is characterized by a lower
case letter "p" followed by a lower case letter designating the
"type" of variable followed by all upper case letters
representing a name for the psuedo-symbol that describes its
function.
dCLIP's PUBLIC arrays alway start with DC* or ADC*, so it
is recommended that you refrain from using PUBLIC memvars
starting with DC* or ADC*. We use PUBLIC arrays rather than
Static arrays for the purposes of speed performance and code
size. dCLIP makes thousands of accesses to information which
cannot be encapsulated within a single .PRG due to Clipper
compiler limitations. For example, when repainting relational
browse screens, accessing this information from a system static
array would require using a function call rather than direct
access, thereby decreasing speed performance.
SCREEN MESSAGE AND MENU DEFINTIONS
All messages written to the screen are defined in *.CH header
files. This allows programmers to change the screen messages
for support of different languages by simply creating a custom
version of the .CH file and recompiling the associated .PRG.
Each _DC*.PRG file has an associated _DC*.CH file which is used
to define the messages and/or menu items. For example, the
main pull-down menu system that is shared by all the Database
Assistant menus is contained in _DCASSIS.PRG and the menu
definitions are in _DCASSIS.PRG.
-- Example of code in _DCASSIS.PRG --
aSub9 := { DC_ASSMSG_10_1, ;
DC_ASSMSG_10_2, ;
DC_ASSMSG_10_3, ;
DC_ASSMSG_10_4, ;
DC_ASSMSG_10_5, ;
DC_ASSMSG_10_6, ;
DC_ASSMSG_10_7 }
-- Example of Code in _DCASSIS.CH --
#define DC_ASSMSG_10_1 "HELP System"
#define DC_ASSMSG_10_2 "TUTORIAL System"
#define DC_ASSMSG_10_3 "DOS ~Gateway Menu"
#define DC_ASSMSG_10_4 "DOS Directory"
#define DC_ASSMSG_10_5 "Dot-~Prompt"
#define DC_ASSMSG_10_6 "Log Status"
#define DC_ASSMSG_10_7 "e~Xit To DOS"
#define DC_ASSMSG_10_8 'HTGDPLX' // Hot-Keys
Note: When re-defining menu items you must also re-define the
Hot-Keys as shown above.
PUBLIC FUNCTIONS
All PUBLIC dCLIP functions start with DC_*() and are
documented in the DCHELP.DBF database and DCLIP.NG Norton
Guide.
STATIC FUNCTIONS
STATIC functions start with _DC*() and are not documented
other than any documentation which may appear in the source
code.