The following IDL internal functions allow the enabling and/or disabling of system routines. Disabled routines will throw an error when called from IDL code.

Note: These routines are primarily meant for authors of Runtime or Callable IDL applications.

IDL_SysRtnEnable()

The IDL_SysRtnEnable() function is used to enable and/or disable system routines.

Syntax

void IDL_SysRtnEnable(int is_function, IDL_STRING *names, 
   IDL_MEMINT n, int option, IDL_SYSRTN_GENERIC disfcn)

Arguments

is_function

Set to TRUE if functions are being manipulated, FALSE for procedures.

names

NULL, or an array of names of routines.

n

The number of names in names.

option

One of the values from the following specify what this routine should do:

  • IDL_SRE_ENABLE (Enable specified routines)
  • IDL_SRE_ENABLE_EXCLUSIVE (Enable specified routines and disable all others)
  • IDL_SRE_DISABLE (Disable specified routines)
  • IDL_SRE_DISABLE_EXCLUSIVE (Disable specified routines and enable all others)

disfcn

NULL, or address of an IDL system routine to be called by the IDL interpreter for these disabled routines. If this argument is not provided, a default routine is used.

Result

All routines are enabled/disabled as specified. If a non-existent routine is specified, it is quietly ignored. Attempts to enable routines disabled for licensing reasons are also quietly ignored.

Note: The routines CALL_FUNCTION, CALL_METHOD (function and procedure), CALL_PROCEDURE, and EXECUTE are not real system routines, but are actually special cases that result in different IDL pcode. For this reason, they cannot be disabled. However, anything they can call can be disabled.

IDL_SysRtnGetEnabledNames()

The IDL_SysRtnGetEnabledNames() function can be used to obtain the names of all system routines which are currently enabled or disabled, either due to licensing reasons or due to a call to IDL_SysRtnEnable().

Syntax

void IDL_SysRtnGetEnabledNames(int is_function, IDL_STRING *str, int enabled)

Arguments

is_function

Set to TRUE if a list of functions is desired, FALSE for a list of procedures.

str

Points to a buffer of IDL_STRING descriptors to fill in. The caller must call IDL_SysRtnNumEnabled() to determine how many such routines exist, and this buffer must be large enough to hold that number.

enabled

Set to TRUE to receive names of enabled routines, FALSE to receive names of disabled ones.

Result

The memory supplied via str is filled in with the desired names.

IDL_SysRtnGetEnabledNames()

The IDL_SysRtnGetEnabledNames() function requires you to supply a buffer large enough to hold all of the names to be returned. IDL_SysRtnNumEnabled() can be called to obtain the number of such routines, allowing you to properly size the buffer.

Syntax

IDL_MEMINT IDL_SysRtnNumEnabled(int is_function, int enabled)

Arguments

is_function

Set to TRUE if the number of functions is desired, FALSE for procedures.

enabled

Set to TRUE to receive number of enabled routines, FALSE to receive number of disabled ones.

Result

Returns the requested count.

IDL_SysRtnGetRealPtr()

The IDL_SysRtnGetRealPtr() routine returns the pointer to the actual internal IDL function that implements the system function or procedure of the specified name.

You can use this routine to interpose your own code between IDL and the actual routine. This process is sometimes called "hooking." To implement such a hook function, you must use the IDL_SysRtnEnable() function to register the interposed routine, which in turn uses IDL_SysRtnGetRealPtr() to obtain the actual IDLfunction pointer for the routine.

Syntax

IDL_SYSRTN_GENERIC IDL_SysRtnGetRealPtr(int is_function, char *name)

Arguments

is_function

Set to TRUE if functions are being manipulated, FALSE for procedures.

name

The name of function or procedure for which the real function pointer is required.

Result

If the specified routine...

  • exists and is not disabled, its function pointer is returned.
  • does not exist, a NULL pointer is returned.
  • has been disabled by the user, its actual function pointer is returned.
  • has been disabled for licensing reasons, the real function pointer does not exist, and the pointer to its stub is returned.

Note: This routine can cause an IDL_MSG_LONGJMP message to be issued if the function comes from a DLM and the DLM load fails due to memory allocation errors. Therefore, it must not be called unless the IDL interpreter is active. The prime intent for this routine is to call it from the stub routine of a disabled function when the interpreter invokes the associated system routine.

IDL_SysRtnGetCurrentName()

To get the IDL name for the currently executing system routine, use IDL_SysRtnGetCurrentName().

Syntax

char *IDL_SysRtnGetCurrentName(void)

This function returns a pointer to the name of the currently executing system routine. If there is no currently executing system routine, a NULL (0) pointer is returned.

This routine will never return NULL if called from within a system routine.