\subsection{externalproc}
\label{labexternalproc}
\noindent Name: \textbf{externalproc}\\
\phantom{aaa}binds an external code to a \sollya procedure\\[0.2cm]
\noindent Library names:\\
\verb|     sollya_obj_t sollya_lib_externalprocedure(sollya_externalprocedure_type_t, |\\
\verb|                                               sollya_externalprocedure_type_t *,|\\
\verb|                                               int, char *, void *);|\\
\verb|     sollya_obj_t sollya_lib_externalprocedure_with_data(|\\
\verb|                                               sollya_externalprocedure_type_t, |\\
\verb|                                               sollya_externalprocedure_type_t *,|\\
\verb|                                               int, char *, void *, void *,|\\
\verb|                                               void (*)(void *));|\\[0.2cm]
\noindent Usage: 
\begin{center}
\textbf{externalproc}(\emph{identifier}, \emph{filename}, \emph{argumenttype} \texttt{->} \emph{resulttype}) : (\textsf{identifier type}, \textsf{string}, \textsf{type type}, \textsf{type type}) $\rightarrow$ \textsf{void}\\
\end{center}
Parameters: 
\begin{itemize}
\item \emph{identifier} represents the identifier the code is to be bound to
\item \emph{filename} of type \textsf{string} represents the name of the object file where the code of procedure can be found
\item \emph{argumenttype} represents a definition of the types of the arguments of the \sollya procedure and the external code
\item \emph{resulttype} represents a definition of the result type of the external code
\end{itemize}
\noindent Description: \begin{itemize}

\item \textbf{externalproc} allows for binding the \sollya identifier \emph{identifier} to an
   external code. After this binding, when \sollya encounters \emph{identifier}
   applied to a list of actual parameters, it will evaluate these parameters and
   call the external code with these parameters. If the external code indicated
   success, it will receive the result produced by the external code, transform
   it to \sollya's internal representation and return it.
    
   In order to allow correct evaluation and typing of the data in parameter and
   in result to be passed to and received from the external code, \textbf{externalproc}
   has a third parameter \emph{argumenttype} \texttt{->} \emph{resulttype}. Both \emph{argumenttype} and
   \emph{resulttype} are one of \textbf{void}, \textbf{constant}, \textbf{function}, \textbf{object}, \textbf{range}, \textbf{integer},
   \textbf{string}, \textbf{boolean}, \textbf{list of} \textbf{constant}, \textbf{list of} \textbf{function}, \textbf{list of} \textbf{object},
   \textbf{list of} \textbf{range}, \textbf{list of} \textbf{integer}, \textbf{list of} \textbf{string}, \textbf{list of} \textbf{boolean}.
    
   It is worth mentionning that the difference between the data and
   result type \textbf{function} and the type \textbf{object} is minimal and due to
   support of legacy \sollya code. Both \sollya functions and \sollya
   objects are transferred from and to the external procedure thru the C
   type \texttt{sollya\_obj\_t}. The difference is that
   \sollya will check that a certain object is a mathematical function
   when \textbf{function} is used as a type, and will skip this test if the
   \textbf{object} type is used. Similarly, \sollya relies on an object produced
   by the external procedure to be a mathematical function when \textbf{function}
   is used and will not make this assumption for \textbf{object}.
    
   If upon a usage of a procedure bound to an external procedure the type of the
   actual parameters given or its number is not correct, \sollya produces a type
   error. An external function not applied to arguments represents itself and
   prints out with its argument and result types.
    
   The external function is supposed to return an integer indicating success. It
   returns its result depending on its \sollya result type as follows. Here, the
   external procedure is assumed to be implemented as a C function.\begin{itemize}
     \item If the \sollya result type is void, the C function has no pointer
        argument for the result.
     \item If the \sollya result type is \textbf{constant}, the first argument of the
        C function is of C type \texttt{mpfr\_t *}, the result is returned by affecting
        the MPFR variable.
     \item If the \sollya result type is \textbf{function}, the first argument of the
        C function is of C type \texttt{sollya\_obj\_t *}, the result is returned by
        affecting the \texttt{sollya\_obj\_t} variable.
     \item If the \sollya result type is \textbf{object}, the first argument of the
        C function is of C type \texttt{sollya\_obj\_t *}, the result is returned by
        affecting the \texttt{sollya\_obj\_t} variable.
     \item If the \sollya result type is \textbf{range}, the first argument of the C function
        is of C type \texttt{mpfi\_t *}, the result is returned by affecting the MPFI
        variable.
     \item If the \sollya result type is \textbf{integer}, the first argument of the
        C function is of C type \texttt{int *}, the result is returned by affecting the
        int variable.
     \item If the \sollya result type is \textbf{string}, the first argument of the
        C function is of C type \texttt{char **}, the result is returned by the \texttt{char *}
        pointed with a new \texttt{char *}.
     \item If the \sollya result type is \textbf{boolean}, the first argument of the
        C function is of C type \texttt{int *}, the result is returned by affecting the
        int variable with a boolean value.
     \item If the \sollya result type is \textbf{list of} type, the first argument of the
        C function is of a C type depending on the \sollya return type:\begin{itemize}
          \item For a list of \textbf{constant}: \verb|sollya_constant_list_t *|
          \item For a list of \textbf{function}: \verb|sollya_obj_list_t *|
          \item For a list of \textbf{object}: \verb|sollya_obj_list_t *|
          \item For a list of \textbf{range}: \verb|sollya_constant_list_t *|
          \item For a list of \textbf{integer}: \verb|sollya_int_list_t *|
          \item For a list of \textbf{string}: \verb|sollya_string_list_t *|
          \item For a list of \textbf{boolean}: \verb|sollya_boolean_list_t *| \end{itemize}
   \end{itemize}
   The external procedure affects its possible pointer argument if and only if
   it succeeds. This means, if the function returns an integer indicating
   failure, it does not leak any memory to the encompassing environment.
    
   The external procedure receives its arguments as follows: If the \sollya
   argument type is \textbf{void}, no argument array is given. Otherwise the C function
   receives a C \texttt{void **} argument representing an array of size equal to the
   arity of the function where each entry (of C type \texttt{void *}) represents a value
   with a C type depending on the corresponding \sollya type.\begin{itemize}
     \item If the \sollya type is \textbf{constant}, the \texttt{void *} is to be cast to \texttt{mpfr\_t *}.
     \item If the \sollya type is \textbf{function}, the \texttt{void *} is to be cast to
        \texttt{sollya\_obj\_t}.
     \item If the \sollya type is \textbf{object}, the \texttt{void *} is to be cast to \texttt{sollya\_obj\_t}.
     \item If the \sollya type is \textbf{range}, the \texttt{void *} is to be cast to \texttt{mpfi\_t *}.
     \item If the \sollya type is \textbf{integer}, the \texttt{void *} is to be cast to \texttt{int *}.
     \item If the \sollya type is \textbf{string}, the \texttt{void *} is to be cast to \texttt{char *}.
     \item If the \sollya type is \textbf{boolean}, the \texttt{void *} is to be cast to \texttt{int *}.
     \item If the \sollya type is \textbf{list of} type, the \texttt{void *} is to be cast to a list
        of a type depending on the type of the list argument:\begin{itemize}
          \item For a list of \textbf{constant}: \verb|sollya_constant_list_t|
          \item For a list of \textbf{function}: \verb|sollya_obj_list_t|
          \item For a list of \textbf{object}: \verb|sollya_obj_list_t|
          \item For a list of \textbf{range}: \verb|sollya_interval_list_t|
          \item For a list of \textbf{integer}: \verb|sollya_int_list_t|
          \item For a list of \textbf{string}: \verb|sollya_string_list_t|
          \item For a list of \textbf{boolean}: \verb|sollya_boolean_list_t| \end{itemize}
   \end{itemize}
   The external procedure is not supposed to alter the memory pointed by its
   array argument \texttt{void **}.
    
   In both directions (argument and result values), empty lists are represented
   by \texttt{NULL} pointers.
    
   Similarly to internal procedures, externally bounded procedures can be
   considered to be objects inside \sollya that can be assigned to other
   variables, stored in list etc.

\item The user should be aware that they may use the \sollya library in external
   codes to be dynamically bound to \sollya using \textbf{externalproc}. On most systems,
   it suffices to include the header of the \sollya library into the source code
   of the external procedure. Linking with the actual \sollya library is not
   necessary on most systems; as the interactive \sollya executable contains a
   superset of the \sollya library functions. On some systems, linking with the
   \sollya library or some of its dependencies may be necessary.
    
   In particular, the \sollya library --~and, of course, its header file~--
   contain a certain set of functions to manipulate lists with elements of
   certain types, such as \verb|sollya_constant_list_t|, \verb|sollya_obj_list_t| and so on.
   As explained above, these types are passed in argument to (and received back
   thru a reference from) an external procedure. These list manipulation
   functions are not strictly necessary to the use of the \sollya library in
   free-standing applications that do not use the functionality provided with
   \textbf{externalproc}. They are therefore provided as-is without any further
   documentation, besides the comments given in the \sollya library header file.

\item The dynamic object file whose name is given to \textbf{externalproc} for binding of
   an external procedure may also define a destructor function
   \verb|int sollya_external_lib_close(void)|. If \sollya finds such a destructor
   function in the dynamic object file, it will call that function when closing
   the dynamic object file again. This happens when \sollya is terminated or when
   the current \sollya session is restarted using \textbf{restart}. The purpose of the
   destructor function is to allow the dynamically bound code to free any memory
   that it might have allocated before \sollya is terminated or restarted.
    
   The dynamic object file is not necessarily needed to define a destructor
   function. This ensure backward compatibility with older \sollya external
   library function object files.
    
   When defined, the destructor function is supposed to return an integer
   value indicating if an error has happened. Upon success, the destructor
   functions is to return a zero value, upon error a non-zero value.
\end{itemize}
\noindent Example 1: 
\begin{center}\begin{minipage}{15cm}\begin{Verbatim}[frame=single]
> bashexecute("gcc -fPIC -Wall -c externalprocexample.c");
> bashexecute("gcc -fPIC -shared -o externalprocexample externalprocexample.o");

> externalproc(foo, "./externalprocexample", (integer, integer) -> integer);
> foo;
foo
> foo(5, 6);
11
> verbosity = 1!;
> foo();
Warning: at least one of the given expressions or a subexpression is not correct
ly typed
or its evaluation has failed because of some error on a side-effect.
error
> a = foo;
> a(5,6);
11
\end{Verbatim}
\end{minipage}\end{center}
See also: \textbf{library} (\ref{lablibrary}), \textbf{libraryconstant} (\ref{lablibraryconstant}), \textbf{externalplot} (\ref{labexternalplot}), \textbf{bashexecute} (\ref{labbashexecute}), \textbf{void} (\ref{labvoid}), \textbf{constant} (\ref{labconstant}), \textbf{function} (\ref{labfunction}), \textbf{range} (\ref{labrange}), \textbf{integer} (\ref{labinteger}), \textbf{string} (\ref{labstring}), \textbf{boolean} (\ref{labboolean}), \textbf{list of} (\ref{lablistof}), \textbf{object} (\ref{labobject})
