The features described in this topic are obsolete
and should not be used in new IDL code.

HANDLE_CREATE

This routine is obsolete and should not be used in new IDL code.

The HANDLE_CREATE function creates a new handle. A "handle" is a dynamically-allocated variable that is identified by a unique integer value known as a "handle ID". Handles can have a value, of any IDL data type and organization, associated with them. This function returns the handle ID of the newly-created handle.

Because handles are dynamic, they can be used to create complex data structures. They are also global in scope, but do not suffer from the limitations of COMMON blocks. That is, handles are available to all program units at all times. (Remember, however, that IDL variables containing handle IDs are not global in scope and must be declared in a COMMON block if you want to share them between program units.)

Handle Terminology

The following terms are used to describe handles in the documentation for this function and other handle-related routines:

Handle ID: The unique integer identifier associated with a handle.

Handle value: Data of any IDL type and organization associated with a handle.

Top-level handle: A handle at the top of a handle hierarchy. A top-level handle can have children, but does not have a parent.

Parents, children, and siblings: These terms describe the relationship between handles in a handle hierarchy. When a new handle is created, it can be the start of a new handle hierarchy (a top-level handle) or it can belong to the level of a handle hierarchy below an existing handle. A handle created in this way is said to be a child of the specified parent. Parents can have any number of children. All handles that share the same parent are said to be siblings.

Syntax

Result = HANDLE_CREATE([ID])

Arguments

ID

If this argument is present, it specifies the handle ID relative to which the new handle is created. Normally, the new handle becomes the last child of the parent handle specified by ID. However, this behavior can be changed by setting the FIRST_CHILD or SIBLING keywords.

Omit this argument to create a new top-level handle without a parent.

Keywords

FIRST_CHILD

Set this keyword to create the new handle as the first child of the handle specified by ID. Any existing children of ID become later siblings of the new first child (i.e., the existing first child becomes the second child, the second child becomes the third child, etc.).

NO_COPY

Usually, when the VALUE keyword is used, the source variable memory is copied to the handle value. If the NO_COPY keyword is set, the value data is taken away from the source variable and attached directly to the destination. This feature can be used to move data very efficiently. However, it has the side effect of causing the source variable to become undefined.

SIBLING

Set this keyword to create the new handle as the sibling handle immediately following ID. Any other siblings currently following ID become later siblings of the new handle. Note that you cannot create a handle that is a sibling of a top-level handle.

VALUE

The value to be assigned to the handle.

Every handle can contain a user-specified value of any data type and organization. This value is not used by the handle in any way, but exists entirely for the convenience of the IDL programmer. Use this keyword to set the handle value when the handle is first created.

If the VALUE keyword is not specified, the handle's initial value is undefined.

Handle values can be retrieved using the HANDLE_VALUE procedure.

Examples

The following commands create a top-level handle with 3 child handles. Each handle is assigned a different string value:

;Create top-level handle without an initial handle value: 
top = HANDLE_CREATE() 
;Create first child of the top-level handle: 
first = HANDLE_CREATE(top, VALUE='First child') 
;Create second child of the top-level handle: 
second = HANDLE_CREATE(top, VALUE='Second child') 
;Create a new sibling between first and second.  
;This handle is also a child of the top-level handle: 
third = HANDLE_CREATE(first, VALUE='Another child', /SIBLING)