Exit

Next: Type Testing Up: Interface to Externals Previous: Argument Passing

Exit

A Prolog procedure, when called, may succeed, fail, or produce an error. There are four basic macros provided as exit points from a C external predicate:

Succeed;

This causes the external procedure to terminate normally with success.

Fail;

This causes the external procedure to terminate normally with failure.

Succeed_If(expr);

This causes the external procedure to succeed if expr is true (in the C definition of truth, i.e. nonzero), otherwise it fails.

Error(ErrorId);

This causes the external procedure to terminate abnormally, raising the error type ErrorId. When Succeed or Fail is called control returns to the Prolog program which called the external procedure, and execution continues normally. A call to Error() is made when for some reason an error has occurred in the execution of the external procedure. The argument to Error() is taken from a list of predefined errors. Upon a call to Error(), control passes to the appropriate error handler, and execution continues as described in the section on error handling. The list of predefined errors is in the file 'error.h'. The most common errors will be:

INSTANTIATION_FAULT

unexpected variable.

TYPE_ERROR

wrong type.

RANGE_ERROR

out of range.

ARITH_EXCEPTION

e.g. division by 0.

SYS_ERROR

operating system error. This assumes that the system variable errno contains the system error number. Before executing the Error macro, the value of errno must be saved using Set_Errno, e.g.:

if (open(path, flags) < 0)
{
    Set_Errno
    Error(SYS_ERROR)
}

If, for instance, the file to open does not exist, this will result in an error message like

system interface error: No such file or directory in my_external(...)

where the text "No such file or directory" is obtained from the operating system.

However, it will rarely be necessary to use the macro Error(), as the macros described in the following provide exit points from external procedures for the most common error cases.

CAUTION: If the external predicate calls another function which uses some of the return or error macros, the external predicate has to test its return code and if it is negative, it must return to Prolog with this value:

int p_my_external(val, tag)
value val;
type  tag;
{
    ...
    if ((err = aux_func(val)) < 0)
    {
        Error(err)
    }
    ...
}

int aux_func(val)
value val;
{
    if (condition(val))
        { Succeed }
    else
        { Error(TYPE_ERROR) }
}

After performing an arithmetic operation on floating point numbers, which might produce an exception, use the macro

Check_Float_Exception()

which raises the corresponding event in the Prolog execution, if necessary.

Next: Type Testing Up: Interface to Externals Previous: Argument Passing

Micha Meier
Mon Mar 4 12:11:45 MET 1996