Registering Routines

IDL_SysRtnAdd()

The IDL_SysRtnAdd() function adds system routines to IDL’s internal tables of system functions and procedures. As a programmer, you will need to call this function directly if you are linking a version of IDL to which you are adding routines, although this is very rare and not considered to be a good practice for maintainability reasons.

More commonly, you use IDL_SysRtnAdd() in the IDL_Load() function of a Dynamically Loadable Module (DLM).

Note: LINKIMAGE or DLMs are the preferred way to add system routines to IDL because they do not require building a separate IDL program. Of the two, we recommend the use of DLMs whenever possible.

Syntax

int IDL_SysRtnAdd(IDL_SYSFUN_DEF2 *defs, int is_function, int cnt)

It returns True if it succeeds in adding the routine or False in the event of an error.

Arguments

defs

An array of IDL_SYSFUN_DEF2 structures, one per routine to be declared. This array must be defined with the C language static storage class because IDL keeps pointers to it. defs must be sorted by routine name in ascending lexical order.

is_function

Set this parameter to IDL_TRUE if the routines in defs are functions, and

IDL_FALSE if they are procedures.

cnt

The number of IDL_SYSFUN_DEF2 structures contained in the defs array. The definition of IDL_SYSFUN_DEF2 is:

typedef IDL_VARIABLE *(* IDL_SYSRTN_GENERIC)();

typedef struct {

   IDL_SYSRTN_GENERIC funct_addr;

   char *name;

   unsigned short arg_min;

   unsigned short arg_max;

   int flags

   void *extra;

   } IDL_SYSFUN_DEF2;

IDL_VARIABLE structures are described in The IDL_VARIABLE Structure.

funct_addr

Address of the function implementing the system routine.

name

The name by which the routine is to be invoked from within IDL. This should be a pointer to a null terminated string. The name should be capitalized. If the routine is an object method, the name should be fully qualified, which means that it should include the class name at the beginning followed by two consecutive colons, followed by the method name (e.g. CLASS::METHOD).

arg_min

The minimum number of arguments allowed for the routine.

arg_max

The maximum number of arguments allowed for the routine. If the routine does not place an upper value on the number of arguments, use the value IDL_MAXPARAMS.

flags

A bitmask that provides additional information about the routine. Its value can be any combination of the following values (bitwise OR-ed together to specify more than one at a time) or zero if no options are necessary:

IDL_SYSFUN_DEF_F_OBSOLETE

IDL should issue a warning message if this routine is called and !WARN.OBS_ROUTINE is set.

IDL_SYSFUN_DEF_F_KEYWORDS

This routine accepts keywords as well as plain arguments.

IDL_SYSFUN_DEF_F_METHOD

This routine is an object method.

extra

Reserved to NV5 Geospatial Solutions. The caller should set this to 0.

Example

The following example shows how to register a system routine linked directly with IDL. For simplicity, everything is placed in a single file. Normally, you would modularize things to allow easier code maintenance.

#include <stdio.h>

#include "idl_export.h"

void prox1(int argc, IDL_VPTR argv[])

{

printf("prox1 %d\n", IDL_LongScalar(argv[0]));

}

main(int argc, char *argv[])

{

static IDL_SYSFUN_DEF2 new_pros[] = {

{(IDL_SYSRTN_GENERIC) prox1, "PROX1", 1, 1, 0, 0}

};

if (!IDL_SysRtnAdd(new_pros, IDL_FALSE, 1)) IDL_Message(IDL_M_GENERIC, IDL_MSG_RET,

"Error adding system routine");

return IDL_Main(0, argc, argv);

}

This adds a system procedure named PROX1 which accepts a single argument. It converts this argument to a scalar longword integer and prints it.