RevMedia

Introduction

The C Interface is a software package from Revelation Technologies to allow Revelation and Advanced Revelation to call C language routines. The C interface gives Revelation and Advanced Revelation (hence forth referred to collectively as Rev) the ability to control devices, to manipulate aspects of the underlying hardware or to use ROM BIOS and DOS services. Links to C also gives a developer an opportunity to use some of the C libraries available, particularly those that can access files, for the creation of Environmental Bonds. C gives speed advantages, particularly in complex numerical calculations. The C interface should not be an excuse to begin re-writing your applications wholesale in C. In a number of instances, particularly string handling, Rev is faster and all file I/O to Rev files must be done via calls to R/Basic. The additional work and effort required means that you would only use C where R/Basic is unable to serve.

This series of articles assumes that you are experienced with R/Basic, and have a working knowledge of C. Some understanding of the 80x86 processors and some familiarity with DOS and the ROM BIOS is also useful.

Requirements In order to create C routines suitable for inclusion into Rev, the following are required in addition to your existing Rev system:

     *    C Interface, version 2.0

     *    Microsoft C, version 5.x or Manx Aztec C86

The Microsoft C compiler version is important. The current version is 6.x The library structures in 6.x have apparently changed making this version incompatible. I have been able to use 6.x, with no apparent ill effects but the requirements are stated, so stick to them! In general, the compiler requirement is a compiler that can produce .COM files. Use of other compilers requires the creation of an assembler module from source provided on the disk.

The Microsoft compiler is preferable and was used for the examples shown in this series.

Development

We will begin by looking straight away at a simple example which will illustrate the basic steps involved. Later we will examine the steps in more detail and some of the design restrictions and rules that must be observed.

The following example, taken from the C interface guide illustrates a simple program which uses the rev_print_string function (taken from the C interface function library) to send a string to the screen or printer. The header file #include revintrf.h, is used to insert a file that declares functions and variables related to the C function library. #INCLUDE is similar to an R/Basic $INSERT statement whilst #define MSC is used to control a pre-compilation process that conditionally includes source code according to which compiler you are using, in this case Microsoft C.

      #define MSC
      #include "revintrf.h"
      main() {
        rev_print_string("  ") ;
        rev_print_string("Hello, World.") ;
      }

The program is compiled by invoking the compiler CL as follows:

      cl -c example.c

The -c option causes compilation to object code only.

The resulting object file is then linked to STARTUP.OBJ and REVMSC.LIB as follows:

      LINK STARTUP example,example,example/MAP,REVMSC/NOE

The linking process resolves references in your C code to external functions by combining your program object code with libraries of standard functions. The /NOE option prevents extended library searches which cause symbol multiply defined errors whilst linking.

The resulting .EXE file is then converted into binary format (which do not relocate in memory) using the utility, EXE2BIN.EXE which is included with DOS.

      exe2bin example.exe

The program example.bin is now ready to be loaded into Rev. This is done using an R/Basic utility provided on the C interface diskette. This program will load and store the program into a Rev file. The program is then catalogued and is ready for testing.

Writing the C Code

The first thing that might strike a C programmer about the code is the use of the function call rev_print_string rather than the more familiar printf which is equivalent to the R/Basic PRINT. The function is one of a list of functions provided for the C programmer to link with R/Basic. The include file REVINTRF.H contains declarations of these functions. They include functions to receive and return variables, to manipulate files, common variable links, and output. C programs can call R/Basic functions, call DOS and BIOS services, and can invoke Rev file operations such as create, open, read, write and so on. The functions are fully documented and in later sections of this series, we will see some in action, particularly in passing variables to and from the C program.

The C code that you intend to adapt or write must also conform to two important rules:

     *    Only the SMALL model can be used, that is, the code and data must
          be fit into 64K. COMPACT or LARGE models will cause fixup errors
          in the EXE2BIN stage making the function unusable. Far pointers
          can be declared to point to variables in Rev string space and
          special versions of some standard C string functions are provided
          on the diskette.

     *    Memory allocation using standard C memory routines such as malloc,
          alloc etc must be avoided. Dynamic memory can be allocated in Rev
          string space but keeping track of it after the
          "garbage collection" means that you need to ask Rev where it is
          before use.

These rules are important for pre-written function libraries which allocate buffers and may also violate the SMALL model rule. Unless the source is available, these libraries may cause problems that would be difficult to pin down.

The next section of this series will use a more complex program to demonstrate a practical example of a C language module and demonstrate the use of the C function library to move variables to and from the C and R/Basic environments.

Mark Hirst is the ICS Advantage Support Manager at ICS. He is also the author of the various graphical utilities found on the last diskette.