
	How To Compile/Link Your Own Function(s) into RLaB

	INTRODUCTION:

	This document describes the process for building and linking
	your own function(s) into RLaB. There are two ways to do this:
	1) compile your function with the rlab source to build a new
	executable, 2) compile your function as a separate
	shared-object, and dynamically link it with rlab using rlab's
	dlopen function.

	Either method requires that you write an interface function so
	that your function can communicate arguments and a return
	value with rlab. The interface function is the same whether
	you compile your function with rlab to make a new executable
	or compile your function as a shared object.

	The end result of this process is the incorporation of your
	function into rlab as a builtin function.

	OVERVIEW:

	Writing an Interface Function:

	All builtin functions are void functions with the same
	argument list. The following is the simplest builtin function
	you could create:

		void
		simplest (return_ptr, n_args, d_arg)
		     VPTR *return_ptr;
		     int n_args;
		     Datum *d_arg;
		{
		  *return_ptr = (VPTR) scalar_Create (0.0);
		}

	The first argument is a pointer to a void pointer and is there
	to facilitate a return argument. The return argument must be a
	valid rlab entity/object. The second argument, n_args,
	contains the number of arguments the function was called
	with. The last argument, d_arg, is an array of Datums, that
	contains all the function's arguments.

	Rlab does not check either the type or the number of arguments
	a builtin function is called with. It is up to the function to
	perform any error checking.

	There is a collection of functions that allow for simple acces
	to the function's arguments stored in d_arg. The following
	example will demonstrate how to check the number of arguments
	and extract each type of argument from d_arg:


		void
		ex2 (return_ptr, n_args, d_arg)
		     VPTR *return_ptr;
		     int n_args;
		     Datum *d_arg;
		{
		  char *str;
		  int s1;
		  char *str;
		  ListNode *M, *S;
		  Matrix *m;

		  if (n_args != 3)
		  {
		    clean_bltin_args (d_arg, n_args);
		    error_1 ("ex2: 3 arguments required", 0);
		  }
		
		  /* Get a string argument. */
		  S = bltin_get_string ("ex2", d_arg, 1);

		  /* Extract the string object from the entity. */
		  str = string_GetString (e_data (S));

		  /* Get a scalar double value. */
		  s1 = (int) bltin_get_numeric_double ("ex2", d_arg, 2);

		  /* Get a matrix argument. */
		  M = bltin_get_numeric_matrix ("ex2", d_arg, 3);

		  /* Extract the matrix object from the entity. */
		  m = (Matrix *) e_data (M);
		
		  /* Call my special purpose function. */
		  call_my_special_function (str, s1, m);

		  /* Clean up any entities. */
		  remove_tmp_destroy (S);
		  remove_tmp_destroy (M);

		  /* Return something. */
		  *return_ptr = (VPTR) scalar_Create (s1);
		}
		  
		
		
	Compiling an Interface Function:

	Linking an Interface Function:

	REFERENCE MATERIAL:
