 
 
 
C.3  Referring to ECLiPSe terms from C
The data types ec_refs and ec_ref provide a means to have non-volatile
references to ECLiPSe data from within C data structures. However,
it must be kept in mind that ECLiPSe data structures are nevertheless
subject to backtracking, which means they may be reset to an earlier
status when the search engine requires it. Creating a reference to
a data structure does not change that in any way. In particular, 
when the search engine fails beyond the state where the reference was
set up, the reference disappears and is also reset to its earlier value.
- 
ec_refs		ec_refs_create(int n,const pword pw)
 create a data structure capable of holding n non-volatile
	references to ECLiPSe data items. They are initialised
	with the value pw, which must be of a simple type.
 
 
- ec_refs		ec_refs_create_newvars(int)
 like ec_refs_create(), but each item is initialised to
	a freshly created ECLiPSe variable.
 
 
- void		ec_refs_destroy(ec_refs)
 destroy the ECLiPSe references. It is important that this
	is done, otherwise the ECLiPSe garbage collector will not
	be able to free the references data structures, which may
	eventually lead to memory overflow.
 
 
- void		ec_refs_set(ec_refs,int i,const pword pw)
 set the i'th reference to the ECLiPSe term pw. This setting is
	subject to the ECLiPSe engine's undo-mechanism on backtracking.
 
 
- pword		ec_refs_get(const ec_refs,int i)
 return the ECLiPSe term referred to by the i'th reference.
 
 
- int		ec_refs_size(const ec_refs)
 return the capacity of the ec_refs data structure.
 
 
- ec_ref		ec_ref_create(pword)
 like ec_refs_create() for a single reference.
 
 
- ec_ref		ec_ref_create_newvar()
 analogous to ec_refs_create_newvars().
 
 
- void		ec_ref_destroy(ec_ref)
 analogous to ec_refs_destroy().
 
 
- void		ec_ref_set(ec_ref,const pword)
 analogous to ec_refs_set().
 
 
- pword		ec_ref_get(const ec_ref)
 analogous to ec_refs_get().
 
 
