REVMEDIA FKB Articles - AREV, OI, REV G, jREV, JCDC, LIVEWATER,ADVANCED REVELATION, OPENINSIGHT, REVELATION G

RevMedia FKB

Document	V3I5A4
Title	Reader's Forum - Mark Hirst Revelation C Interface - Part 1
Keywords	C RBASIC INTERFACE FOD ROM BIOS DOS
Text	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 (Volume 3 Issue 5 Pages 8 10)

[revmedia/copyrigh.htm]

Page last modified: 31/01/03