From Matthew Probert · 1996-04-05 00:18 · #75220 in R25C
INTERFACING C WITH CLIPPER
Matthew Probert
Servile Software
The information in this info journal was written for the Clipper
Summer '87 compiler, whether or not it still holds for Clipper 5 I do
not know.
The Clipper programming language is a popular xBase environment for
the PC. However, it lacks many of the facilities available to
programmers of other languages, and it is quite slow compared to C.
Because of this there are a large number of third party add-on
libraries available for Clipper which provide the facilities lacked.
As a programmer you probably want to write your own library for
Clipper, or perhaps individual functions to cater for circumstances
which Clipper cannot handle, such as high resolution graphics.
COMPILING AND LINKING
The Clipper extend functions allow user defined functions to be
written in C, linked with and used by the Clipper application.
The first problem a programmer must address when writing functions in
C to link with a Clipper application is that of the C compiler's run
time libraries.
If one is writing functions with Microsoft C, then most of the
required run time library functions will be found in the
Clipper.lib and Extend.lib libraries which are part of Clipper.
If, however, one is using a different C compiler, such as Borland's
Turbo C then the run time library routines must be supplied on the
link line.
All C functions must be compiled using the large memory model the
following line is used with Microsoft C
cl /c /AL /Zl /Oalt /FPa /Gs <program.c>
and this compile line may be used with Turbo C
tcc -c -ml <program>
simply substitute <program> for the program name to be compiled.
(Change tcc for bcc to compile with Borland C).
Having compiled a C function it must be linked in with the
application. If the C function was compiled with Microsoft C then the
link line will look a little like this;
LINK /SE:500 /NOE program.obj cfunc.obj,,,Clipper Extend
If the C function was linked with another C compiler you will also
need to link in the C run time libraries, for example to link in the
Turbo C large memory mode library use the following link line;
LINK /SE:500 /NOE program.obj cfunc.obj,,,Clipper Extend cl
If one is using a number of separately compiled C functions it is a
good idea to collect them in a library. If you are using Microsoft C
then you can simply create the library by using Microsoft Lib.exe
with the following command line;
LIB mylib +prog1 +prog2, NUL, NUL
This tells the librarian to add prog1.obj and prog2.obj to a library
called mylib.lib, creating it if it does not exist. The NUL parameter
is for supressing the listing file.
If you have been using another C compiler you should copy the C large
memory model run time library before adding your functions to it for
example;
COPY C:\TURBOC\LIB\cl.lib mylib.lib
LIB mylib +prog1 +prog2, NUL, NUL
Then when you link your Clipper application you will use a link line
similar to;
LINK /SE:500 /NOE myprog,,,Clipper Extend Mylib
Often when linking C functions with Clipper applications link errors
will occur such as those shown below;
Microsoft (R) Overlay Linker Version 3.65
Copyright (C) Microsoft Corp 1983-1988. All rights reserved.
LINK : error L2029: Unresolved externals:
FIWRQQ in file(s):
M:SLIB.LIB(TEST)
FIDRQQ in file(s):
M:SLIB.LIB(TEST)
There were 2 errors detected
Example Link Errors
The errors shown here are 'Unresolved externals', that is they are
references to functions which are not found in any of the object
modules or libraries specified on the link line. These occur because
the C compilers often scatter functions and variables through a number
of libraries. In tracking these functions down use may be made of
the Microsoft librarian list file option. If you run Lib.Exe on the
Turbo C 'emu.lib' library file and specify a listing file as follows;
LIB emu,emu.lst
The librarian will create an ascii file which contains the names of
each object module contained in the specified library file, and the
names of each function and public variable declared in each object
module, as shown in this listing of Borland's EMU.LIB library.
e086_Entry........EMU086 e086_Shortcut.....EMU086
e087_Entry........EMU087 e087_Shortcut.....EMU087
FIARQQ............EMUINIT FICRQQ............EMUINIT
FIDRQQ............EMUINIT FIERQQ............EMUINIT
FISRQQ............EMUINIT FIWRQQ............EMUINIT
FJARQQ............EMUINIT FJCRQQ............EMUINIT
FJSRQQ............EMUINIT __EMURESET........EMUINIT
EMUINIT Offset: 00000010H Code and data size: 1a2H
FIARQQ FICRQQ FIDRQQ FIERQQ
FISRQQ FIWRQQ FJARQQ FJCRQQ
FJSRQQ __EMURESET
EMU086 Offset: 00000470H Code and data size: 2630H
e086_Entry e086_Shortcut
EMU087 Offset: 00003200H Code and data size: 417H
e087_Entry e087_Shortcut
Example Library List File
+Function/variable
| +Object module name
| |
e086_Entry........EMU086 e086_Shortcut.....EMU086
FJSRQQ............EMUINIT __EMURESET........EMUINIT
+-Object module name +Offset within library
| | +Size of module
| | |
EMUINIT Offset: 00000010H Code and data size: 1a2H
FIARQQ FICRQQ FIDRQQ FIERQQ
FISRQQ FIWRQQ FJARQQ FJCRQQ
FJSRQQ __EMURESET
Description Of Library List File
Receiving Parameters
Clipper provides six different functions for receiving parameters in a
C function. These functions are;
Receive a string char * _parc(int,[int])
Receive a Date string char * _pards(int,[int])
Receive a logical int _parl(int,[int])
Receive an integer int _parni(int,[int])
Receive a long long _parnl(int,[int])
Receive a double double _parnd(int,[int])
To illustrate simple parameter receiving in a C function I offer the
following simple C function which receives two numeric parameters from
the calling Clipper program, and uses these two numeric parameters
to set the size of the cursor.
#include <nandef.h> /* Clipper header files */
#include <extend.h>
#include <dos.h> /* Header file to define REGS */
CLIPPER s_curset()
{
/* Demonstration function to set cursor shape */
union REGS inreg,outreg;
inreg.h.ah = 0x01;
inreg.h.ch = _parni(1); /* Get integer parameter 1 */
inreg.h.cl = _parni(2); /* Get integer parameter 2 */
int86(0x10,&inreg,&outreg);
_ret(); /* Return to Clipper */
}
Clipper provides four more functions for dealing with received
parameters; _parclen(int,[int]) which returns the length of a string
including imbedded '\0's, _parcsiz(int[int]) which returns the
length of a character string passed by reference from Clipper,
_parinfa(int,[int]) which returns the type of a specified array
element or the length of an array, and finally _parinfo(int)
whic returns the type of a parameter.
The following example function uses _parinfa() to determine both the
length of an array passed from a Clipper program, and the type of
each element in the array. The function then returns to Clipper an
integer representing the number of defined elements in the array.
#include <nandef.h>
#include <extend.h>
CLIPPER s_alen()
{
int total;
int n;
int defined;
int type;
/* Return the number of defined elements in an array */
/* From Clipper use defined = s_alen(arr) */
total = _parinfa(1,0); /* Get declared number of elements in array */
defined = 0;
for (n = 1; n <= total; n++){
type = _parinfa(1,n); /* Get array parameter type */
if (type)
defined++;
}
_retni(defined); /* Return an integer to Clipper */
}
This function goes one step further to return the mean average of all
numeric values in an array. Notice the use of _parnd() to retrieve the
numeric values as doubles. You may find that because of the floating
point arithmetic in this function that it will only work if compiled
with Microsoft C.
#include <nandef.h>
#include <extend.h>
CLIPPER s_aave()
{
int total;
int defined;
int n;
int type;
double sum;
/* Return the mean average value of numbers in array */
/* From Clipper use mean = s_aave(arr)
total = _parinfa(1,0); /* Get declared number of elements */
defined = 0;
for (n = 1; n <= total; n++){ /* Determine number of defined */
type = _parinfa(1,n); /* elements */
if (type == 2)
defined++;
}
sum = 0;
for (n = 1; n <= total; n++){
type = _parinfa(1,n);
if (type == 2) /* Only sum numeric values */
sum += _parnd(1,n);
}
_retnd(sum / defined); /* Return a double to Clipper */
}
Returning Values
The Clipper manual lists seven functions for returning from a function
written in another language. These return functions for C are as
follows;
character _retc(char *)
date _retds(char *)
logical _retl(int)
numeric (int) _retni(int)
numeric (long) _retnl(long)
numeric (double) _retnd(double)
nothing _ret(void)
Omitted from the Clipper manual is the information that you may return
different types of value back from a function! For example, you may
wish to return a character string under normal circumstances, fine use
_retc(). On error occurences however you can return a logical using
_retl(). The Clipper program will assign the received value to the
receiving variable in the correct manner.
The following simple C function returns a random number. Notice the
use of integers which limits the range of the function to +-32767.
For larger values you should use longs instead of integers.
#include <nandef.h>
#include <extend.h>
#include <dos.h>
CLIPPER s_random()
{
/* Returns a random number between 0 and param1 - 1 */
/* From Clipper use x = s_random(param1) */
int param1;
int x;
param1 = _parni(1);
x = rand() % param1;
_retni(x);
}
This function receives a string from Clipper, and passes back an
upper case copy of the string, leaving the original unchanged. The
maximum length of the string which can be processed is determined
by the size of target[], here set to 5000 characters.
#include <nandef.h>
#include <extend.h>
CLIPPER s_upper()
{
/* Returns an upper case copy of string */
/* From Clipper use ? s_upper("this is a string")
char *p;
char *q;
char *string;
char target[5000];
int n;
string = _parc(1);
p = string;
q = target;
while(*string){
*q++ = toupper(*string);
string++;
}
*q = '\0';
string = p;
_retc(target);
}
This function may be used to change the current DOS directory. If it
is successful it returns .T. to the calling Clipper program,
otherwise it returns .F.
#include <nandef.h>
#include <extend.h>
#include <dos.h>
CLIPPER s_chdir()
{
/* Attempts to change the current DOS directory */
/* From Clipper use result = s_chdir(path) */
union REGS inreg,outreg;
struct SREGS segreg;
char *path;
int x;
path = _parc(1); /* Retrieve string from Clipper */
inreg.h.ah = 0x3b;
segreg.ds = FP_SEG(path);
inreg.x.dx = FP_OFF(path);
intdosx(&inreg,&outreg,&segreg);
x = outreg.x.ax;
if (x == 3)
_retl(0); /* Return logical .F. back to Clipper */
else
_retl(1); /* Return logical .T. back to Clipper */
}
Avoiding Unresolved Externals
As we have already seen, a common problem plaguing the programmer
interfacing C functions with Clipper programs is Unresolved Externals.
The following example C function called s_print() will not link with
Clipper.
#include <nandef.h>
#include <extend.h>
#include <stdio.h>
CLIPPER s_print()
{
char *x;
x = _parc(1);
printf("\nI received %s from Clipper.\n",x);
_ret();
}
The linker gives you the following reply;
Microsoft (R) Overlay Linker Version 3.65
Copyright (C) Microsoft Corp 1983-1988. All rights reserved.
M:SLIB.LIB(IOERROR) : error L2025: __doserrno : symbol defined more than once
pos: 16C6F Record type: 53C6
LINK : error L2029: Unresolved externals:
__RealCvtVector in file(s):
M:SLIB.LIB(REALCVT)
_abort in file(s):
M:SLIB.LIB(CVTFAK)
There were 3 errors detected
The error L2025 'symbol defined more than once' can in this case be
ignored. However, the unresolved externals 'RealCvtVector' and 'abort'
cannot be ignored. These two functions are referenced by the function
printf() which has been included in the C function. The answer is to
use as few of the compiler's run time library functions as possible,
use ROM calls instead with INT86() and INTDOSX() etc.
Adding High Resolution Graphics To Clipper With C
The most annoying omission from Clipper, in my opinion, is the lack of
high resolution graphics facilities. The following functions, written
in Turbo C, provide high resolution graphics to Clipper.
First we require a means to change the video display mode to a high
resolution graphics mode, and back to text mode. The IBM PC BIOS
provides the means for this and can be called from C as follows;
/* Servile Software Library For Clipper */
#include <nandef.h>
#include <extend.h>
#include <dos.h>
CLIPPER s_smode()
{
/* Set Video Mode */
/* From Clipper use s_smode(mode) */
union REGS inreg,outreg;
inreg.h.al = _parni(1);
inreg.h.ah = 0x00;
int86 (0x10, &inreg, &outreg);
/* 1 40x25 colour text
2 40x25 bw text
3 80x25 colour text
4 320x200 4 colour graphics
5 320x200 4 colour graphics colour burst off
6 640x200 2 colour graphics
etc
*/
_ret();
}
Having set the computer into graphics mode, how about setting pixels
to a specified colour?
/* Servile Software Library For Clipper */
#include <nandef.h>
#include <extend.h>
#include <dos.h>
CLIPPER s_plot()
{
union REGS inreg,outreg;
/* Sets a pixel at the specified coordinates to the specified
colour. */
inreg.h.bh = 0x00;
inreg.x.cx = _parni(1);
inreg.x.dx = _parni(2);
inreg.h.al = _parni(3);
inreg.h.ah = 0x0C;
int86(0x10, &inreg, &outreg);
}
Line drawing and circles are handled by these two functions;
/* Servile Software Library For Clipper */
#include <nandef.h>
#include <extend.h>
#include <dos.h>
CLIPPER s_line()
{
union REGS inreg,outreg;
/* Draws a straight line from (a,b) to (c,d) in colour col */
int a;
int b;
int c;
int d;
int col;
int u;
int v;
int d1x;
int d1y;
int d2x;
int d2y;
int m;
int n;
int s;
int i;
a = _parni(1);
b = _parni(2);
c = _parni(3);
d = _parni(4);
col = _parni(5);
u = c - a;
v = d - b;
if (u == 0)
{
d1x = 0;
m = 0;
}
else
{
m = abs(u);
if (u < 0)
d1x = -1;
else
if (u > 0)
d1x = 1;
}
if ( v == 0)
{
d1y = 0;
n = 0;
}
else
{
n = abs(v);
--- WILDMAIL!/WC v4.12
* Origin: Ooh! BBS, London [MULTILINES] 0181-395-3108 (2:254/233.0)