Changes were required to implement the ability to enable and disable IDL system routines from runtime and callable IDL. Rather than alter the IDL_SYSFUN_DEF structure, and the IDL_AddSystemRoutine() function in an incompatible way, a new structure (IDL_SYSFUN_DEF2) and new function (IDL_SysRtnAdd()) have been created to accomplish the new tasks, and the old structure and function have been obsoleted.
Note: The interfaces described in this section are considered functionally obsolete although they continue to be supported by NV5 Geospatial Solutions. This section is supplied to help those maintaining older code. New code should be written using the information found in Registering Routines.
Registering Routines
The IDL_AddSystemRoutine() 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_AddSystemRoutine() 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. These mechanisms are discussed in the following sections.
int IDL_AddSystemRoutine(IDL_SYSFUN_DEF *defs, int is_function, int cnt)
It returns True if it succeeds in adding the routine or False in the event of an error:
defs
An array of IDL_SYSFUN_DEF 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_DEF structures contained in the defs array. The definition of IDL_SYSFUN_DEF is:
typedef IDL_VARIABLE *(* IDL_FUN_RET)()
typedef struct { IDL_FUN_RET funct_addr
UCHAR arg_min
UCHAR arg_max
} IDL_SYSFUN_DEF
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’d 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.