[ 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

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

## Description

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

record
  see record_create/1 and local record/1 declaration
shelf
  see shelf_create/2,3 and local shelf/1 declaration
store
  see store_create/1 and local store/1 declaration
stream
  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

- name_to_handle(+, +, -) is semidet

### Modules

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

### Exceptions

(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

## Examples

        % 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