[ ECLiPSe Externals built-in.|Group Index| Full Index]

external(+PredSpec, +CName)

Defines PredSpec to be a deterministic external predicate linked to the C function whose system name is CName.

+PredSpec
Of the form Atom/Integer (predicate name/arity).
+CName
Atom or string.

Description

Declares PredSpec to be a deterministic external predicate (in the caller module) linked to the ``C'' function whose system name is CName.

If the visibility of PredSpec is not declared, it is set to local.

If necessary, an underscore is prepended to CName to get its form as used by the C compiler.

If a call to PredSpec has already been compiled as a Prolog call or a non-deterministic external call, error 62 is raised (``inconsistent procedure redefinition''). This can be prevented by defining the external before compiling any call to it or by using the declaration predicate external/1.

Fail Conditions

None.

Resatisfiable

No.

Exceptions

(4) Instantiation fault
Either PredSpec or CName is not instantiated.
(5) Type error
PredSpec is not of the form Atom/Integer.
(5) Type error
CName is not an atom or a string.
(62)
A call to PredSpec has already been compiled as a Prolog call or a non-deterministic external call.
(211)
External function does not exist.

Examples


Success:

   % file to create a deterministic external predicate.
      % cat msg.c

   % external.h contains the macros for the external interface.
      #include        "external.h"
      p_prmsg(v, t)
      value           v;
      type            t;
      {
            Check_String(t);
            Fprintf(Current_Output, "message: ");
            Write(v, t, Current_Output);
            Succeed;
      }


   % compile with ECLiPSe include files.
      % cc -c -I/usr/local/ECLIPSE/include msg.c
      % eclipse
      ECLiPSe Version n.nn, mm/dd/yy Copyright ECRC GmbH

   % load the .o file dynamically into the system with math option.
      [eclipse]: load('msg.o').
      yes.
      [eclipse]: current_predicate(prmsg/1).
      no.

   % link the object file with a predicate definition.
      [eclipse]: external(prmsg/1, p_prmsg).
      yes.

   % check on existence and flags of prmsg/1.
      [eclipse]: get_flag(prmsg/1, type, Type),
              get_flag(prmsg/1, call_type, Call_type),
              get_flag(prmsg/1, visibility, Vis).
      Type = user
      Call_type = external
      Vis = local     More? (;)
      yes.

   % use prmsg/1.
      [eclipse]: prmsg("prolog").
      message: prolog
      yes.

Error:
      external(PredSpec, "p_member"). (Error 4).
      external(p/0, S).               (Error 4).
      external('p/0', p_p0).          (Error 5).
      external(p/0, 123).             (Error 5).

      [eclipse]: [user].
       p :- a.
       user   compiled 32 bytes in 0.00 seconds
      yes.
      [eclipse]: external(a/0, c_a).   (Error 62).

      external(prmsg/1,"p_prmsg1").  (Error 211).
              % call load/1,2 first.


See Also

b_external / 1, external / 1, external / 2, load / 1