&k1S  CALLING "C" BINARIES FROM TECH BASIC&k0S

                         GVG / 12 February 1986 / V1.1


+ HPUX Technical BASIC allows you to call "C" subroutines from BASIC and pass
parameters to them, using the CALLBIN statement.  This note outlines the syntax
of CALLBIN, explains how to write a "C" subroutine to be used through CALLBIN,
explains how to compile the "C" subroutine and connect it to a BASIC program,
and illustrates the whole process with an example.

&dD&k3SThe CALLBIN Statement&k0S&d@

+ The CALLBIN statement has the syntax:


   [CALLBIN]-+->["]->[subroutine name]->["]-+-+-------------------------+->
             |                              ^ |                         ^
             |                              | |                         |
             +----->[string expression]-----+ +->[(]->[parameters]->[)]-+


The "string expression" is any expression that returns a string as a value - in
this case, a string that gives the name of a "C" subroutine.  The syntax of the
"parameters" is as follows:


  +--------------------[,]<----------------------+
  |                                              |
  V                                              |
 -+-+->[variable name]--+--------------------+-+-+->   <--- passed by address
    |                   |                    ^ ^
    |                   |                    | |
    |                   +->[(]-+------+->[)]-+ |
    |                          |      ^        |
    |                          |      |        |
    |                          +->[,]-+        |
    |                                          |
    |                                          |
    +---->[(]->[simple variable name]->[)]---->+        <-+
    |                                          |          |
    |                                          |          |
    +------------>[array element]------------->+        <-+
    |                                          |          |
    |                                          |          |
    +-------------->[constant]---------------->+        <-+- passed by value
    |                                          |          |
    |                                          |          |
    +---------->["]->[literal]->["]----------->+        <-+
    |                                          |          |
    |                                          |          |
    +-->[arithmetic / relational expression]---+        <-+


+ Let me review some facts of life about BASIC variable types before I go on
and give details about the preceding syntax diagram.  BASIC uses the following
variable types:

  + Simple numeric variables -  either REAL, SHORT, or INTEGER; default is
    REAL.  (REAL types are 64-bit floating-point numbers; SHORT types are
    32-bit floating-point numbers; INTEGER types are 32-bit signed integers.)

  + Numeric array variables - again, either REAL, SHORT, or INTEGER; default is
    REAL.  Such arrays can have one or two dimensions.  The lower bound of each
    dimension is "0" by default, although it can be set to be "1"; IT MUST BE
    LEFT ZERO IF YOU WANT TO USE THE ARRAY AS A PARAMETER FOR A "C" SUBROUTINE.
    The maximum upper bound of each dimension is 65,530.

  + Simple string variables - essentially an array of ASCII characters (bytes),
    up to 65,530 characters long (although the default size is 18 characters).
    (String variables always have a "$" at the end of their name; numeric
    variables never do.  String constants - like, say, "balderdash", are
    actually string arrays and can be accessed as such.)  A string contained in
    a string variable must be ended by a "null" character if you want to pass
    it to a "C" subroutine as a parameter.  This can be done in several ways;
    you could, for example, use the the string "string~0", or the string
    expression "hello" & CHR$(0).  (There are some other peculiarities to using
    strings as parameters to "C" subroutines that I'll get to in a moment.)

  + Arrays of string variables - subject to the same restrictions on
    dimensions, bounds, and size as numeric arrays.

BASIC also deals with other objects, like:

  + Constants - either numeric or string (like, say, "Floyd").

  + Literals - String expressions, including string variables, string
    constants, or string functions (like CHR$), or combinations of all
    three.

  + Arithmetic expressions - like, say, "4*somevar".

  + Relational expressions - like, say, "somevar<9".  A relational expression
    evaluates to "1" if true and to "O" if false.

+ The syntax diagram indicates that you can send the address of any of these
variables to a "C" subroutine simply by giving the name of the variable -
WITHOUT parentheses - as a parameter to CALLBIN.  For example, if you want to
pass the address of a numeric variable, say COUNT, and a string variable, say
NAME$ to a "C" subroutine, you would simply enter:

                         CALLBIN "Csub" (COUNT,NAME$);

But why send the address?  (This is called "call by address", by the way.)
Because the alternative is to just the send the VALUE contained in the variable
to the "C" subroutine - which means that the subroutine CAN'T CHANGE THE
VARIABLE BECAUSE ALL IT HAS IS ITS CONTENTS!  (This is called "call by value".)
Sending the address gives the subroutine access to the variable itself.  THIS
IS THE ONLY WAY THE C SUBROUTINE CAN PASS VALUES BACK TO THE CALLING ROUTINE.

Sending the addresses of arrays is just as easy.  Suppose you have an array
named SOMEARRAY.  Then you would pass the array as SOMEARRAY().  If that array
was a two-dimensional array, then you would pass its address as SOMEARRAY(,).

The only place where sending addresses to the "C" subroutine gets really tricky
is in sending string variables (that is, arrays of characters).  The problem
comes up because BASIC and "C" have entirely different ways of figuring out how
many characters are in a string variable.  (Lest there be confusion, the
number of characters in a string is NOT the same as the length of the string
variable.  The length of the string variable is fixed; the number of characters
in it may vary from none to the length of the string.)

"C" expects all strings to have a null character at the end (which is why, as I
mentioned earlier, you have to make sure you put a null at the end of the
string);  the only way a "C" subroutine can figure out how many characters
are in the string is to count the number of characters before the null.

BASIC, on the other hand, keeps the number of characters in a string variable
in another variable that a "C" subroutine can't get at.  So what's the problem?
The problem is that if the "C" subroutine is passed the address of a string
variable, and then loads a string LONGER than the one already in the variable,
BASIC will not "see" any of the characters in the new string that exceed the
number of characters in the old.

You have to do some pushups to take care of this problem.  There's two steps:

1: Pad the string variable with blanks all the way to its end; easy to do, all
you need is the command:

     somestring$[LEN(somestring$)+1]=" "

(It doesn't seem obvious that this should work, but one of our support
engineers checked it out interactively as follows:

     DIM Z$[15]
     LET Z$="hello"
     Z$
     hello
     LEN(Z$)
      5
     LET Z$[LEN(Z$)+1]=" "
     Z$
     hello
     LEN(Z$)
      15
     Z$
     hello

Piece of cake.)

You have to take some precautions, however, since trying to do this to a string
variable that's already full will cause an error.  (Use the LEN command.)

You can now pass the address of the string to the "C" subroutine as a
parameter.

2: Once you get the string back, you have to figure out how many characters the
string has passed back.  There's two ways to do this:

First, you could pass the address of a simple variable to the "C" subroutine
and have it return the number of characters in the string; then you would
assign the number of characters to the string as:

     somestring$ = somestring$[1,howlong]

- where "howlong" is the simple variable passed to the "C" subroutine.

Second, you could search the string for the null character at its end and use
that to assign the length at follows:

     nullpos = POS(somestring$,CHR$(0))
     somestring$ = somestring[1,nullpos-1]

(Enough, already!  Let's move on.)

+ The syntax diagram also indicates that you can send the VALUE of a simple
numeric variable simply by enclosing the variable name in parentheses; for
example:

                           CALLBIN "Csub" ((COUNT));

- sends the value of COUNT to a subroutine.

You can also send the VALUE of a single array element by giving its name and
array index:

                       CALLBIN "Csub" (SOMEARRAY[1][6]);

(There is, by the way, no convenient way to send the address of a single array
element.)

Finally, you can send constants - either numeric or string - or the results of
arithmetic or relational expressions as values to "C" subroutines:

             CALLBIN "Csub" (27,"Floyd~0",4*COUNT, COUNT<ENDVALUE);

Note also that a string does NOT have to be padded (since no value is being
returned); however, you still have to tack a null character onto the end.
Note, finally, that a string constant can also be made up of the output of
string expressions like CHR$ (which returns the character corresponding to a
given numeric code.

&dD&k3SWriting the "C" Subroutine&k0S&d@

+ You write the "C" subroutine just as you would write any "C" subroutine for
separate compilation.

There's a subtle point to be aware of here, however.  Formally speaking, there
are no "subroutines" in "C"; all subprograms are FUNCTIONS that return a value
directly.  For example, if we write a function named "getsomevalue" that does
some arbitary computation on an input, a "C" program can get the value back
from it directly:

     buffer = getsomevalue(input);

THIS WON'T WORK USING CALLBIN!  You have to write the function in the form of a
SUBROUTINE that is passed the ADDRESS of a variable that it can use for output
back to the main program.  The subprogram "getsomevalue" would have to be
rewritten so that a "C" program would call it in the following way:

     getsomevalue(&buffer,input)

- where "&buffer" is the address of a variable used for output.  (Of course,
there may be no reason to use different variables for input and output ... that
depends on the situation.)

+ If the "C" subroutine is sent the address of a variable, its dummy parameter
is a pointer to the variable and declared as such.  For example, if CALLBIN is
sending the address of an INTEGER variable count to the "C" subroutine "Csub",
as shown below:

                            CALLBIN "CSub" (COUNT);

- then the C subroutine must make the declaration:

     Csub(cnt)
     int *cnt;      /* "cnt" is a pointer to an int. */
     ...

If COUNT was actually a REAL, you'd make the declaration:

     Csub(cnt)
     double *cnt;   /* "cnt" is a pointer to a double. */
     ...

(I'll explain why it's declared "double" in a little while.)

If the "C" subroutine is sent the value of a variable, its dummy parameter is
actually a "local" variable that contains the value; this local variable can be
modified without changing the original variable in the BASIC program.  For
example, if you wanted to just send the value of COUNT, you would write:

                           CALLBIN "CSub" ((COUNT));

- and:

     Csub(cnt)
     int cnt;      /* "cnt" is a local int variable. */
     ...

If COUNT was a REAL, of course, you'd have to change the declaration a little:

     Csub(cnt)
     double cnt;      /* "cnt" is a local double variable. */
     ...

You'd make similar declarations to handle any other numeric parameter sent to
the subroutine as a value - array elements, numeric constants, results of
expressions, and so on.

+ Suppose you're passing an address.  The following table shows how to
represent the address of the following BASIC "simple" variables, using an
arbitrary pointer variable named "ptr".

     REAL                                    double *ptr
     SHORT                                   float  *ptr
     INTEGER                                 int *ptr
     STRING VARIABLE                         char *ptr

You could make the same declarations for accessing arrays (actually, a string
variable IS an "array of char"), although you would have to do pointer
arithmetic and operations to get the proper array element.  That's not too hard
for a one-dimensional array, but it might be more convienient to make the
following (entirely equivalent) declarations, using an arbitrary array name
"mat":

     REAL array                              double mat[]
     SHORT array                             float  mat[]
     INTEGER array                           int mat[]
     STRING VARIABLE                         char mat[]

Of course, the subroutine must have some way of knowing where the END of the
one-dimensional array is - so it doesn't try to access memory beyond the end of
the array, and crash something.  ("C" always expects a string to be terminated
with a null character - which is why any string sent to a "C" subroutine must
be terminated by a null; it tells where the end of the string is.)

For two-dimensional arrays (remember that Tech BASIC can't handle arrays with
more than two dimensions), pointer arithmetic becomes confusing.  You can pass
the address of a two-dimensional array to a subroutine and access it as a two-
dimensional array within the subroutine AS LONG AS THE SUBROUTINE KNOWS HOW BIG
THE SECOND ARRAY DIMENSION IS.  Suppose, for example, you wanted to pass an 8x4
array of some arbitrary type - sat INTEGER - to a subroutine.  Then, in the
subroutine, you would declare:

     int mat[][4];

You could also declare BOTH array dimensions if you wished.  You CAN'T pass the
array dimensions to the subroutine as a parameter, by the way - it's part of a
declaration, and has to be known at compilation.

An array of strings is a special case.  A one-dimensional array of strings is
actually a two-dimensional array, since each string is an array of characters
in the first place.  You could do this:

     char **ptr;

- which means that "ptr" points to a pointer to characters, or you could make
the roughly equivalent declaration:

     char *mat[];

- which means that "mat" is an array of pointers to characters.  Of course, you
could use a similar representation for a two-dimensional array of characters,
as long as you knew the second array dimension:

     char *mat[][6];

(There are actually several other perfectly equivalent ways to handle string
arrays, but I will not continue on this subject any further.)

+ If you're passing VALUES, rather than addresses, to a "C" subroutine, you
have to be careful, since some types change when they are passed as values:

     + BASIC INTEGER values become "C" type "int".
     + BASIC REAL values become "C" type "double".
     + BASIC SHORT values become "C" type "double".
     + String variables, string constants, and string expressions end up as
       arrays of char (as before).
     + Values sent by arithmetic or relational expression parameters are "C"
       type "double".

+ One last (but certainly NOT least) caution on writing a "C" subroutine: YOU
CAN'T RELIABLY ACCESS THE SAME I/O THAT BASIC IS USING!  This means, for
example, that YOU CAN'T DO PRINTFS OR PUTCHARS TO STANDARD OUT!  You can't
use files that BASIC is using!  The "C" subroutine does NOT have access to the
data structures that control BASIC I/O (unless you are awfully clever).  The C
subroutine, however, CAN access its own I/O, using reads, writes, fprintfs, and
the like.

(Actually, it isn't exactly that cut-and-dried; the second revision of this
document will discuss this subject in more detail - whenever I get the time to
write the thing.)


&dD&k3SCompiling the C Subroutines&k0S&d@

Now suppose you have written one or more "C" subroutines and have them in a
single file, named, say, "dummy.c".  You can compile all the subroutines into a
single object file, using the "C" compiler's "-c" (separate compilation)
option:

     cc -c dummy.c

(You use "fcc" instead of "cc" if you're using the floppy-disc based compiler.)

This gives an object file named "dummy.o" in the current directory.  This file
still needs to be linked with all the proper libraries; you use the link editor
as follows:

     ld -rd dummy.o -lc

The "-r" option makes the resulting code relocatable (so it can be placed
anywhere in memory that BASIC pleases to put it); the "d" options forces
allocation of all variables, so the subroutine will have all the variables it
requires; and the "-lc" option loads all the usual "C" libraries into the
subroutine. (If you need any special "C" libraries, you list their names in
front of "-lc".)  The result will be placed in the "/tmp" directory as "a.out";
you may rename it as you please.  If you want to place the executable code into
a file of your choice - "output" for example -  you can use the "-o" link
editor option instead:

     ld -rdo output dummy.o -lc

+ Now that you've (presumably) learned all of this, I have to tell you that it
doesn't work!  There's a bug in BASIC (which will hopefully be corrected in the
future) that will blow you out of the water if you try to do arithmetic on REAL
or SHORT (floating-point) numbers in a "C" subroutine.  Fortunately, there's an
easy fix.

In order to understand this bug, you need to take a quick look at how programs
are compiled and linked.  When you normally compile "C" programs, a routine
called "start" is included that performs some initial setups and then calls the
rest of the program.

One of the things that "start" does is indicate that a floating-point card is
present or absent, using a "magic floating point variable".

The problem comes up because CALLBIN calls the "C" subroutine directly, without
going through "start"; the magic floating point variable never gets
initialized.  When floating-point operations are used in a binary, BASIC dies
when the "C" subroutine is called.

The problem is easy to fix; all you have to do is initialize the magic
floating-point variable yourself.  First, you write a simple assembly-language
program that simply initializes a variable:

     			globl          float_soft
     			data
	float_soft      dc.w 1

(Please note that the assembler is very picky about column order; the elements
in this program must be in their proper columns.)  Put this in a file named
"fix.s" (as good a name as any) and assemble it:

     as fix.s

This creates an object file called "fix.o".  Finally, you just link it in with
the "C" subroutine:

     ld -rdo output dummy.o fix.o -lc

- and everything should work correctly.

&dD&k3SRunning the "C" Subroutines&k0S&d@

Running the subroutines is easy: all you do is get into BASIC and type LOADBIN
"filename", where "filename" is the path name of the object file of "C"
subroutines.

If you're running BASIC off of floppy disc, you can also place the name of the
object file (or files) of "C" subroutines in another file called ".bconfig" in
the same directory as the BASIC program.  When you fire up BASIC, it will go
check the ".bconfig" file and load all the "C" subroutines automatically.

(If BASIC is in ROM, the ".bconfig" file can be placed in the working
directory.)

That's all there is to it; once the subroutines have been loaded, you can do
CALLBINS to them as you please.

&dD&k3SExamples&k0S&d@

+ A Sample BASIC Program:

10 ! Program to test calling "C" subroutines from Tech BASIC
20 !
30 INTEGER x,y,z
40 DISP "Hello, world."
50 DISP "Enter two numbers that you would like to add:"; @ INPUT x,y
60 LOADBIN "binfile"               ! Load an object file called "binfile".
70 DISP "Binary loaded."
80 CALLBIN "add_numbers" ((x),(y),z)    ! Call the subroutine.
90 ! "add_numbers" gets VALUES of x & y as input, ADDRESS of z for output.
100 DISP "Back from the binary; z=";z
110 SCRATCHBIN "binfile"                ! Get rid of the binary.
120 STOP
130 END


The source code for the "C" subroutine "add_numbers" (which is compiled and
placed in the object file "binfile") has the form:


     add_numbers (a,b,c)
     int a,b,*c;
     {
          *c = a + b;
     }

Notice that the value of the result is passed directly into the variable in the
main program.