[ External Interface | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]

# xset(+Handle, +Index, +Value)

Set the Index-th field of an external data structure (referenced by Handle) to Value.

Handle
  An external data handle.
Index
  An integer.
Value
  A term.

## Description

ECLiPSe can manipulate external data structures via handles. An external data handle can only be created by external code. It consists of a pointer to the external data and a descriptor for this data (a method table). ECLiPSe can then perform certain operations on the data using this method table.

The xset/3 predicate invokes one of the methods, the set-method. The intended meaning is that a field of the external data structure (indicated by Index) is set to the given Value. This setting qualifies as a side-effect (similar to writing to a file) and is not undone on backtracking. The details of how the index is interpreted and which values are allowed depend on the set-method supplied by external code.

### Modes and Determinism

- xset(+, +, +) is semidet

### Fail Conditions

Fails if the set-method specifies failure for certain arguments

### Exceptions

(4) instantiation fault
  Handle or Index is uninstantiated.
(5) type error
  Handle is not a handle, or Index is not an integer.
(141) unimplemented functionality
  The set-method is not implemented for this handle.
(other)
  The set-method can raise any exception

## Examples

        /* C code with embedded ECLiPSe call, passing data via C ararys */
        #include "eclipse.h"

        #define N 5
        double data_in[N] = {1.1,2.2,3.3,4.4,5.5};
        double data_out[N];

        main()
        {
            pword   call;
            int     i;

            ec_init();
            ec_post_string("[my_code]");
            ec_post_goal(
                ec_term(ec_did("process", 3),
                    ec_long(N),
                    ec_handle(&ec_xt_double_arr, (t_ext_ptr) data_in),
                    ec_handle(&ec_xt_double_arr, (t_ext_ptr) data_out)
                )
            );
            if (ec_resume() == PSUCCEED)
            {
                for (i=0; i<N; i++)
                    printf("%f,", data_out[i]);
            }
            ec_cleanup();
        }

        /* ECLiPSe code in file my_code.pl */

        process(0, _, _) :- !.
        process(N, In, Out) :-
            N1 is N-1,
            xget(In, N1, X),
            Y is sqrt(X),
            xset(Out, N1, Y),
            process(N1, In, Out).

        /* Sample run */

        % main
        1.048809,1.483240,1.816590,2.097618,2.345208,

## See Also

xget / 3, subscript / 3