
name_to_handle(+Type, +Name, -Handle)

   Obtain a handle for a named object

Arguments
   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

Type
   Non-logical Variables, Arrays, Bags, Shelves and Stores

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 --- Type or Name are uninstantiated
     5 --- Type is not an atom
     5 --- 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
