Using External Calls
Chapter 11. Integrating External Routines

The functions in programs increment and decrement are now available to GT.M through the shareable library libcrement.sl or libcrement.so, or though the DLL as libcrement.dll, depending on the specific platform. The suffix .sl is used throughout the following examples to represent .sl, .so, or .dll. Be sure to use the appropriate suffix for your platform.

GT.M uses an "external call table" to map the typeless data of M into the typed data of C, and vice versa. The external call table has a first line containing the pathname of the shareable library file followed by one or more specification lines in the following format:

entryref: return-value routine-name (parameter, parameter, ... ) [: SIGSAFE]      

The optional case-insensitive keyword SIGSAFE following the parameter list specifies the external call does not create its own signal handlers; this allows GT.M to avoid burdensome signal handler coordination for the external call. By default, GT.M saves and restores signal setups for external calls.

entryref is an M entryref, return-value is gtm_long_t, gtm_status_t, or void, and parameters are in the format:

direction:type [num]

where [num] indicates a pre-allocation value explained later in this chapter.

Legal directions are I, O, or IO for input, output, or input/output, respectively.

The following table describes the legal types defined in the C header file $gtm_dist/gtmxc_types.h:

Type : Usage

void: Specifies that the function does not return a value.

gtm_status_t : Type int. If the function returns zero (0), then the call was successful. If it returns a non-zero value, GT.M will signal an error upon returning to M.

gtm_long_t : 32-bit signed integer on 32-bit platforms and 64-bit signed integer on 64-bit platforms.

gtm_ulong_t : 32-bit unsigned integer on 32-bit platforms and 64-bit signed integer on 64-bit platforms.

gtm_long_t* : For passing a pointer to long [integers].

gtm_float_t* : For passing a pointer to floating point numbers.

gtm_double_t* : Same as above, but double precision.

gtm_char_t*: For passing a "C" style string - null terminated.

gtm_char_t** : For passing a pointer to a "C" style string.

gtm_string_t* : For passing a structure in the form {int length;char *address}. Useful for moving blocks of memory to or from GT.M.

gtm_pointertofunc_t : For passing callback function pointers. For details see “Callback Mechanism”.

Note

If an external call's function argument is defined in the external call table, GT.M allows invoking that function without specifying a value of the argument. All non-trailing and output-only arguments arguments which do not specify a value translate to the following default values in C: All numeric types: 0 gtm_char_t * and gtm_char_t **: Empty string gtm_string_t *: A structure with 'length' field matching the preallocation size and 'address' field being a NULL pointer. In the mathpak package example, the following invocation translate inval to the default value, that is, 0. GTM>do &mathpak.increment(,.outval) If an external call's function argument is defined in the external call table and that function is invoked without specifying the argument, ensure that the external call function appropriately handles the missing argument. As a good programming practice, always ensure that count of arguments defined in the external call table matches the function invocation. To protect the process, GT.M turns any return values containing a null pointer to an empty string value and, for the first occurrence in a process, sends one XCRETNULLREF syslog message. If an external call sets a gtm_string length to a negative value, to protect the process, GT.M turns any return with a negative length to an empty string value and, for the first occurrence in a process, sends one XCCONVERT syslog message.

gtmxc_types.h also includes definitions for the following entry points exported from libgtmshr:

void gtm_hiber_start(gtm_uint_t mssleep);
void gtm_hiber_start_wait_any(gtm_uint_t mssleep)
void gtm_start_timer(gtm_tid_t tid, gtm_int_t time_to_expir, void (*handler)(), gtm_int_t hdata_len, void \*hdata);
void gtm_cancel_timer(gtm_tid_t tid);

where:

gtm_hiber_start() always sleeps until the time expires; gtm_hiber_start_wait_any() sleeps until the time expires or an interrupt by any signal (including another timer). gtm_start_timer() starts a timer but returns immediately (no sleeping) and drives the given handler when time expires unless the timer is canceled.

	Important
	GT.M continues to support xc_* equivalent types of gtm_* for upward compatibility. gtmxc_types.h explicitly marks the xc_* equivalent types as deprecated.

The first parameter of each called routine is an int (for example, int argc in decrement.c and increment.c) that specifies the number of parameters passed. This parameter is implicit and only appears in the called routine. It does not appear in the call table specification, or in the M invocation. If there are no explicit parameters, the call table specification will have a zero (0) value because this value does not include itself in the count. If there are fewer actual parameters than formal parameters, the call is determined from the parameters specified by the values supplied by the M program. The remaining parameters are undefined. If there are more actual parameters than formal parameters, GT.M reports an error.

There may be only a single occurrence of the type gtm_status_t for each entryref.

Pre-allocation of Output Parameters

The definition of parameters passed by reference with direction output can include specification of a pre-allocation value. This is the number of units of memory that the user wants GT.M to allocate before passing the parameter to the external routine. For example, in the case of type gtm_char_t *, the pre-allocation value would be the number of bytes to be allocated before the call to the external routine.

Specification of a pre-allocation value should follow these rules:

• Pre-allocation is an unsigned integer value specifying the number of bytes to be allocated on the system heap with a pointer passed into the external call.

• Pre-allocating on a type with a direction of input or input/output results in a GT.M error.

• Pre-allocation is meaningful only on types gtm_char_t * and gtm_string_t *. On all other types the pre-allocation value specified will be ignored and the parameter will be allocated a default value for that type. With gtm_string_t * arguments make sure to set the 'length' field appropriately before returning control to GT.M. On return from the external call, GT.M uses the value in the length field as the length of the returned value, in bytes.

• If the user does not specify any value, then the default pre-allocation value would be assigned to the parameter.

• Specification of pre-allocation for "scalar" types (parameters which are passed by value) is an error.

Important

Pre-allocation is optional for all output-only parameters except gtm_string_t * and gtm_char_t *. Pre-allocation yields better management of memory for the external call. When an external call exceeds its specified preallocation (gtm_string_t * or gtm_char_t * output), GT.M produces the EXCEEDSPREALLOC error. In the case the user allocates space for the character pointer inside a gtm_string_t * type output parameter, a length field longer than the specified preallocate size for the output parameter does not cause an EXCEEDSPREALLOC error.

Callback Mechanism

GT.M exposes certain functions that are internal to the GT.M runtime library for the external calls via a callback mechanism. While making an external call, GT.M populates and exposes a table of function pointers containing addresses to call-back functions.

Index	Function	Argument	Type	Description
0	hiber_start			sleep for a specified time
		slp_time	integer	milliseconds to sleep
1	hiber_start_wait_any			sleep for a specified time or until any interrupt, whichever comes first
		slp_time	integer	milliseconds to sleep
2	start_timer			start a timer and invoke a handler function when the timer expires
		tid	integer	unique user specified identifier for this timer
		time_to_expire	integer	milliseconds before handler is invoked
		handler	pointer to function	specifies the entry of the handler function to invoke
		hlen	integer	length of data to be passed via the hdata argument
		hdata	pointer to char	data (if any) to pass to the handler function
3	cancel_timer			stop a timer previously started with start_timer(), if it has not yet expired
		tid	integer	unique user specified identifier of the timer to cancel
4	gtm_malloc			allocates process memory from the heap
		<return-value>	pointer to void	address of the allocated space
		space_needed	32-bit platforms: 32-bit unsigned integer 64-bit platforms: 64-bit unsigned integer	bytes of space to allocate. This has the same signature as the system malloc() call.
5	gtm_free			return memory previously allocated with gtm_malloc()
		free_address	pointer to void	address of the previously allocated space

The external routine can access and invoke a call-back function in any of the following mechanisms:

• While making an external call, GT.M sets the environment variable GTM_CALLIN_START to point to a string containing the start address (decimal integer value) of the table described above. The external routine needs to read this environment variable, convert the string into an integer value and should index into the appropriate entry to call the appropriate GT.M function.

• GT.M also provides an input-only parameter type gtm_pointertofunc_t that can be used to obtain call-back function pointers via parameters in the external routine. If a parameter is specified as I:gtm_pointertofunc_t and if a numeric value (between 0-5) is passed for this parameter in M, GT.M interprets this value as the index into the callback table and passes the appropriate callback function pointer to the external routine.

	Note
	FIS strongly discourages the use of signals, especially SIGALARM, in user written C functions. GT.M assumes that it has complete control over any signals that occur and depends on that behavior for recovery if anything should go wrong. The use of exposed timer APIs should be considered for timer needs.

foo: void bar (I:gtm_float_t*, O:gtm_float_t*)

% echo $GTMXC_mathpak
/user/joe/mathpak.xc
% echo lib /usr/
% cat mathpak.xc
$lib/mathpak.sl
exp: gtm_status_t xexp(I:gtm_float_t*, O:gtm_float_t*)
% cat exp.c
...
int xexp(count, invar, outvar)
int count;
float *invar;
float *outvar;
       {
        ...
       }
% gtm
... 
GTM>d &mathpak.exp(inval,.outval)
GTM>

% echo $GTMXC_extcall
/usr/joe/extcall.xc
% cat extcall.xc
/usr/lib/extcall.sl
prealloc: void gtm_pre_alloc_a(O:gtm_char_t *[12])
% cat extcall.c
#include <stdio.h>
#include <string.h>
#include "gtmxc_types.h"
void gtm_pre_alloc_a (int count, char *arg_prealloca)
{
    strcpy(arg_prealloca, "New Message");
    return;
}

% echo $GTMXC 
/usr/joe/callback.xc 
% cat /usr/joe/callback.xc 
$MYLIB/callback.sl 
init:     void   init_callbacks() 
tstslp:  void   tst_sleep(I:gtm_long_t) 
strtmr: void   start_timer(I:gtm_long_t, I:gtm_long_t) 
% cat /usr/joe/callback.c 
#include <stdio.h> 
#include <stdlib.h> 
 
#include "gtmxc_types.h" 
 
void **functable; 
void (*sleep_uninterrupted)(int ); 
void (*sleep_interrupted)(int ); 
void (*setup_timer)(int , int , void (*)() , int , char *); 
void (*cancel_timer)(int ); 
void* (*malloc_fn)(int); 
void (*free_fn)(void*); 
 
void  init_callbacks (int count) 
{ 
   char *start_address; 
 
   start_address = (char *)getenv("GTM_CALLIN_START"); 
 
   if (start_address == (char *)0) 
   { 
           fprintf(stderr,"GTM_CALLIN_START is not set\n"); 
      return; 
   } 
   functable = (void **)atoi(start_address); 
   if (functable == (void **)0) 
   { 
     perror("atoi : "); 
     fprintf(stderr,"addresses defined by GTM_CALLIN_START not a number\n"); 
     return; 
   } 
   sleep_uninterrupted = (void (*)(int )) functable[0]; 
   sleep_interrupted = (void (*)(int )) functable[1]; 
   setup_timer = (void (*)(int , int, void (*)(), int, char *)) functable[2]; 
   cancel_timer = (void (*)(int )) functable[3]; 
 
   malloc_fn = (void* (*)(int)) functable[4]; 
   free_fn = (void (*)(void*)) functable[5]; 
 
   return; 
} 
 
void  sleep (int count, int time) 
{ 
   (*sleep_uninterrupted)(time); 
} 
 
void timer_handler () 
{ 
   fprintf(stderr,"Timer Handler called\n"); 
   /* Do something */ 
} 
 
void  start_timer (int count, int time_to_int, int time_to_sleep) 
{ 
   (*setup_timer)((int )start_timer, time_to_int, timer_handler, 0, 0); 
   return; 
} 
void* xmalloc (int count) 
{   
return (*malloc_fn)(count); 
} 
 
void  xfree(void* ptr) 
{ 
   (*free_fn)(ptr); 
} 

% echo $GTMXC
/usr/joe/callback.xc
% cat /usr/joe/callback.xc
/usr/lib/callback.sl
init: void init_callbacks(I:gtm_pointertofunc_t, I:gtm_pointertofunc_t)
% gtm
GTM> do &.init(4,5)
GTM>
% cat /usr/joe/callback.c
#include <stdio.h>
#include <stdlib.h>
#include "gtmxc_types.h"
void* (*malloc_fn)(int);
void (*free_fn)(void*);
void init_callbacks(int count, void* (*m)(int), void (*f)(void*))
{
    malloc_fn = m;
    free_fn = f;
}