IDL Pointer Tools

Last Updated June 21, 1999 (Added pointer array create/free capability)



While converting IDL4 handles to IDL5 pointers in my SHARP application, I found it very useful to have pointer wrapper routines which behaved the same as the obsolete HANDLE_CREATE, HANDLE_FREE, HANDLE_INFO, and HANDLE_VALUE routines (type '? obsolete' at the IDL5 prompt for obsolete routine information). The wrapper routines are presented here to assist others who may be converting from using handles to pointers.

At the suggestion of Craig Markwardt, all the routines (except the service routine POINTER_SETGETV5) work under IDL5 and IDL4, allowing for easier porting from IDL4 to IDL5. It is also possible to create or free an array of pointers.

POINTER_CREATE: Create a single pointer, or an array of pointers.

This routine mimics the behavior of PTR_NEW (IDL5) and HANDLE_CREATE (IDL4). Differences include:
- Written as a procedure instead of a function. This allows the input argument to be checked to see if it's already a valid pointer. If it is a valid pointer, the pointer is freed and then re-created (this helps to avoid dangling references).
- Does not accept any keywords (HANDLE_CREATE accepts the keywords FIRST_CHILD, NO_COPY, SIBLING, and VALUE).
Examples:
IDL> pointer_create, ptr
IDL> help, ptr
IDL> pointer_create, ptr, npointers=10
IDL> help, ptr

POINTER_FREE: Free a single pointer, or an array of pointers.

This routine mimics the behavior of PTR_FREE (IDL5) and HANDLE_FREE (IDL4).
Example:
IDL> pointer_create, ptr
IDL> pointer_free, ptr

POINTER_VALID: Check a single variable to see if it is a valid pointer.

This routine mimics the behavior of PTR_VALID (IDL5) and HANDLE_INFO (IDL4). Differences include:
- Does not accept any keywords (HANDLE_INFO accepts the keywords FIRST_CHILD, NUM_CHILDREN, PARENT, SIBLING, VALID_ID).
Example:
IDL> pointer_create, ptr
IDL> help, pointer_valid(ptr)

POINTER_VALUE: Set or get the value of a single pointer.

(Requires the service routine POINTER_SETGETV5)
This routine mimics the behavior of the dereference operator * (IDL5) and HANDLE_VALUE (IDL4).
Example:
IDL> pointer_create, ptr
IDL> pointer_value, ptr, dist(256), /set
IDL> pointer_value, ptr, val
IDL> help, val

With the aid of these routines, all I needed to do to convert handles to pointers was:
(1) Convert function calls to HANDLE_CREATE to procedure calls to POINTER_CREATE,
(2) Globally replace all remaining instances of 'handle' to 'pointer'.
Please let me know if you have any comments, suggestions, or questions.


Liam E. Gumley
Last updated 21 June 1999