[ External Interface | 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

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