[ Non-logical Variables, Arrays, Bags, Shelves and Stores | Reference Manual | Alphabetic Index ]

name_to_handle(+Type, +Name, -Handle)

Obtain a handle for a named object
One of the atoms 'record', 'shelf', 'store' or 'stream'
The name of an object (atom or compound)
A variable that will be unified with a handle


Some types of ECLiPSe objects can alternatively be referred to by a name (alias) or by anonymous handle. These include

see record_create/1 and local record/1 declaration
see shelf_create/2,3 and local shelf/1 declaration
see store_create/1 and local store/1 declaration
see open/3,4

This predicate maps a name to a handle, i.e. it obtains an anonymous handle for an existing named object. This is needed when one wants to use generic operations (such as mutual exclusion or conditions for thread synchronisation) on the object, because the corresponding primitives accept only handles.

Note that for some types of object, Name can be a compound term. In those cases, only the functor (name/arity) of Name is important for the lookup.

Generally, alias names should be used sparingly, because they prevent automatic garbage collection of objects.

Modes and Determinism


This predicate is sensitive to its module context (tool predicate, see @/2).

Fail Conditions

Fails if there is no visible object of type Type with name Name


(4) instantiation fault
Type or Name are uninstantiated
(5) type error
Type is not an atom
(5) type error
Name is not an atom or compound term


    % Get a handle for the current 'output' stream
    ?- name_to_handle(stream, output, H).
    H = $&(stream,1)
    Yes (0.00s cpu)

    % Declare a store and a record, then get handles:
    ?- local store(shed).
    Yes (0.00s cpu)

    ?- local record(foo/1).
    Yes (0.00s cpu)

    ?- name_to_handle(store, shed, H).
    H = $&(store,"17h3")
    Yes (0.00s cpu)

    ?- name_to_handle(shelf, shed, H).
    No (0.00s cpu)

    ?- name_to_handle(record, foo, H).
    No (0.00s cpu)

    ?- name_to_handle(record, foo(_), H).
    H = $&(record,"371bt3")
    Yes (0.00s cpu)

See Also

store / 1, local / 1, is_handle / 1, is_handle / 2