IDL_Savefile::Names

The IDL_Savefile::Names function method returns names, or heap variable identifiers, of items contained within the SAVE file. By default, this method returns the names of variables in the file; keywords can be used to obtain identifiers for other items.

Syntax

Return Value

If the SAVE file contains one or more items of the specified type, the return value is a string array containing the names of the items. If no items of the specified type exist, the return value is a scalar null string.

Note: If either the OBJECT_HEAPVAR or the POINTER_HEAPVAR keyword is specified, the return value is an integer array containing integer values that can be used to recover the heap variables stored in the SAVE file. If no heap variables of the specified type exist, the return value is 0 (zero).

Arguments

None.

Keywords

Note: The Names method will only return the names of one type of item in a single call. With the exception of the COUNT keyword, specifying more than one keyword may cause the method to return unexpected results (most often an empty string).

COMMON_BLOCK

Set this keyword to retrieve the names of any main-level COMMON blocks contained in the SAVE file. A main-level COMMON block item in a SAVE file consists of the name of the block and the names of the variables contained within it. (The values of the variables are saved separately, as normal variables.)

COMMON_VARIABLE

Set this keyword to a scalar string that contains the name of a main-level COMMON block. The value returned by the Names method will be a string array containing the names of the variables contained in the specified COMMON block.

COUNT

Set this keyword equal to a named variable that will contain the number of identifiers returned. A value of 0 (zero) indicates that no identifiers of the specified type exist in the SAVE file, and that the result from the function is either a scalar null string or 0 (zero). A nonzero value indicates that the result is an array with that number of elements.

FUNCTION

Set this keyword to return the names of the compiled functions contained in the SAVE file.

OBJECT_HEAPVAR

Set this keyword to return the integer heap identifiers for the object heap variables contained in the SAVE file.

Note: It is rarely (if ever) necessary to restore heap variables directly; in almost all cases, restoring the regular variable that refers to the heap variable produces the desired effect. See Restoring Heap Variables Directly for a complete discussion of this topic.

Because the heap identifiers contained in the SAVE file being queried were assigned by the IDL session that saved the variables in the file, and not (in general) by the currently executing IDL session, the integers returned when OBJECT_HEAPVAR is set are not valid heap identifiers within the current IDL session. Because of this, the values are returned as plain integer values, and not as object references. The returned integer values can be supplied to the IDL_Savefile::Restore method (using the OBJECT_HEAPVAR keyword) to recover the object heap variables they reference.

Note: Only heap variables whose save attribute is set to True (the default) will are saved. See HEAP_SAVE for additional details on save attributes.

POINTER_HEAPVAR

Set this keyword to return the integer heap identifiers for the pointer heap variables contained in the SAVE file.

Because the heap identifiers contained in the SAVE file being queried were assigned by the IDL session that saved the variables in the file, and not (in general) by the currently executing IDL session, the integers returned when POINTER_HEAPVAR is set are not valid heap identifiers within the current IDL session. Because of this, the values are returned as plain integer values, and not as pointer references. The returned integer values can be supplied to the IDL_Savefile::Restore method (using the POINTER_HEAPVAR keyword) to recover the pointer heap variables they reference.

Note: Only heap variables whose save attribute is set to True (the default) will are saved. See HEAP_SAVE for additional details on save attributes.

PROCEDURE

Set this keyword to return the names of the compiled procedures contained in the SAVE file.

STRUCTURE_DEFINITION

Structure definitions are saved by IDL as a side effect of saving structure variables that use the structure definition. Set this keyword to return the names of the structure definitions contained in the SAVE file.

SYSTEM_VARIABLE

Set this keyword to return the names of system variables contained in the SAVE file.

Example

See Example.

Version History

6.1	Introduced