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

# trace_call_port(+Port, ?Invoc, ?Term)

Create a user-defined debugger port (CALL-style).

Port
  An atom.
Invoc
  An integer or variable.
Term
  Any term.

## Description

This predicate allows to generate a user-defined debugger port, thus enhancing the debugger's basic box model with application- specific checkpoints. In the box model, the execution is viewed as consisting of nested boxes, which are being entered via CALL or REDO ports, and left via EXIT, FAIL or LEAVE ports.

When the debugger is on, this predicate causes a new box to be entered, i.e. a trace line to be displayed with Port being the name of the port, invocation number Invoc and Term in the goal position.

It is important to use a corresponding trace_exit_port/0 call after every call to trace_call_port/3, otherwise the debugger's box nesting will get out of sync. Note however, that fail ports for the new box will be generated automatically.

If Invoc is left uninstantiated, it will be instantiated to a unique invocation number by the system.

### Modes and Determinism

- trace_call_port(+, +, ?) is det
- trace_call_port(+, -, ?) is det

### Modules

This predicate is sensitive to its module context (tool predicate, see @/2).

## Examples

        search(Vars) :-
    	trace_call_port(search_enter, _Invoc, search(Vars)),
    	labeling(Vars),
    	trace_exit_port.

    ?- length(L, 3), L :: 1..4, search(L).
      (1) 1 CALL  length(L, 3)   %> zap to port: [~ call] search_enter
      (6) 2 SEARCH_ENTER  search([_501{[... .. ...]}, _514{[...]}, _527{...}])   %> skip
      (6) 2 *EXIT  search([1, 1, 1])   %> skip

## See Also

trace_point_port / 3, trace_parent_port / 1, trace_exit_port / 0, spy_term / 2, spy_var / 1, trace / 1