A Simple Example of MathLink

This post shows how to use MathLink in the simplest scenario.  This post will show how to make Mathematica run a C program that takes the two inputs and returns the sum, all using MathLink.
A MathLink project consists of a minimum of two files.  One is the C program itself and the second is a template file that tells Mathematica how to interact with the C program.  To join the files together there is a program called mprep, supplied by Mathematica, which converts the template to C code.  In this post I will not use mprep but instead use the program mcc which makes use of mprep and is simpler.  An explanation of how to use mprep will be given in a post about calling FORTRAN with MathLink.


Now let us begin with the code.  Begin by writing a C function that solves the required problem.  Here I will tackle the challenge of adding two integers, x and y.  An appropriate C function is,

int f(int x, int y) {
    return x*y;
}

To produce a complete C program there are two further components, both of which are standard for any MathLink exercise.  One is a header file "mathlink.h" and the second is the main body of the program which is supplied by Mathematica.  It is,

int main(int argc, char *argv[]) {
    return MLMain(argc, argv);
}

Putting all three components together gives the complete C program,

#include "mathlink.h"

int f(int x, int y) {
    return x+y;
}

int main(int argc, char *argv[]) {
    return MLMain(argc, argv);
}

Next for the template file.  There is a guide to writing the template file in the Mathematica documentation.  Here is the template guide, the link also runs through the example solved here.  The template file is quite self-explanatory.  It explains that the function is called f, requires two integer inputs, x and y, and will return and integer.  Here it is,

:Begin:
:Function:      f
:Pattern:       f[x_Integer, y_Integer]
:Arguments:     {x, y}
:ArgumentTypes: {Integer, Integer}
:ReturnType:    Integer
:End:

Place this code in to a file which must have a .tm extension.  I will be using f.tm.  My C program will be called f.c.  To compile the code, open a terminal and type,

terminal $ mcc f.c f.tm -o output

The -o flag is optional and just controls the name of the resulting executable file as usual.

It is now possible to use the function f in Mathematica.  After opening Mathematica, one needs the command Install[argument] where the argument is the path to the executable, here called output, that has been generated.  After the command is executed Mathematica should be able to use f.  To try it one can type f[2,3] and Mathematica should reply 5!

What MathLink does is to give a library that contains the C command MLMain(argc, argv*).  The argument argc refers to the name of the function.  Therefore, the name of the function in the C code and the name in the template file must match.  They will then match the name of the function in Mathematica.  (So one can name the C code file and the template file as one wishes.)  When the function is installed in Mathematica, and then called, Mathematica passes the string that names the function in the argument argc and the arguments of the function in argv*.  All of this is unraveled in the C program to call the corresponding function.