Generic Handle Functions

The following functions take as an argument any type of handle, though some of these functions may do nothing if passed an inappropriate handle type. In particular, for functions that operate on lists, the following handle types are meaningful:

Object	Handle Type
string	stringlist_handle
object	object_handle
property	prpty_handle
device	device_handle
device contact	dev_contact_handle
subcircuit	subckt_handle
subcircuit contact	subc_contact_handle
terminal	terminal_handle

(int) NumHandles()
This returns the number of handles of all types currently in the hash table. It can be used as a check to make sure handles are being properly closed (and thus removed from the table) in the user's scripts.

(int) HandleContent(handle)
This function returns the number of objects currently referenced by the list-type handle passed as an argument. The return value is 1 for other types of handle. The return value is 0 for an empty or closed handle.

(int) HandleTruncate(handle, count)
This function truncates the list referenced by the handle, leaving the current item plus at most count additional items. If count is negative, it is taken as 0. The function returns 1 on success, or 0 if the handle does not reference a list or is not found.

(int) HandleNext(handle)
This function will advance the handle to reference the next element in its list, for handle types that reference a list. It has no effect on other handles. If there were no objects left in the list, or the handle was not found, 0 is returned, otherwise 1 is returned.

(handle) HandleDup(handle)
This function will duplicate a handle and its underlying reference or list of references. The new handle is not associated with the old, and should be iterated through or closed explicitly. For file descriptors, the return value is a duplicate descriptor to the underlying file, with the same read/write mode and file position as the original handle. If the function succeeds, a handle value is returned. If the function fails, 0 is returned.

(handle) HandleDupNitems(handle, count)
This function acts similarly to HandleDup, however for handles that are references to lists, the new handle will reference the current item plus at most count additional items. For handles that are not references to lists, the count argument is ignored. The new handle is returned on success, 0 is returned if there was an error.

(handle) H(scalar)
This function creates a handle from an integer variable. This is needed for using the handle values stored in the array created with the HandleArray function, or otherwise. Array elements are numeric variables, and can not be passed directly to functions expecting handles. This function performs the necessary data conversion.

Example:

SomeFunction(H(handle_array[3])).

Array elements are always numeric variables, though it is possible to assign a handle value to an array element. In order to use as a handle an array element so defined, the H function must be applied. Since scalar variables become handles when assigned from a handle, the H function should never be needed for scalar variables.

(int) HandleArray(handle, array)
This function will create a new handle for every object in the list referenced by the handle argument, and add that handle identifier to the array. Each new handle references a single object. The array argument is the name of a previously defined array variable. The array will be resized if necessary, if possible. It is not possible to resize an array referenced through a pointer, or an array with pointer references. The function returns 0 if the array cannot be resized and resizing is needed. The number of new handles is returned, which will be 0 if the handle argument is empty or does not reference a list. The handles in the array of handle identifiers can be closed conveniently with the CloseArray function. Since the array elements are numeric quantities and not handles, they can not be passed directly to functions expecting handles. The H function should be used to create a temporary handle variable from the array elements when a handle is needed: for example, HandleNext(H(array[2])).

(int) HandleCat(handle1, handle2)
This function will add a copy of the list referenced by the second handle to the end of the list referenced by the first handle. Both arguments must be handles referencing lists of the same kind. The return value is nonzero for success, 0 otherwise.

(int) HandleReverse(handle)
This function will reverse the order of the list referenced by the handle. Calling this function on other types of handles does nothing. The function returns 1 if the action was successful, 0 otherwise.

(int) HandlePurgeList(handle1, handle2)
This function removes from the list referenced by the second handle any items that are also found in the list referenced by the first handle. Both handles must reference lists of the same type. The return value is 1 on success, 0 otherwise.

(int) Close(handle)
This function deletes and frees the handle. It can be used to free up resources when a handle is no longer in use. In particular, for file handles, the underlying file descriptor is closed by calling this function. The return value is 1 if the handle is closed successfully, 0 if the handle is not found in the internal hash table or some other error occurs.

(int) CloseArray(array, size)
This function will call Close on the first size elements of the array. The array is assumed to be an array of handles as returned from HandleArray. The function will fail if the array is not an array variable. The return value is always 1.