Event Types

## C.1 Event Types

- Argument Types and Values
- Arithmetic, Environment
- Data and Memory Areas, Predicates, Operators
- Modules, Visibility
- Syntax Errors, Parsing
- Compilation, Run-Time System, Execution
- Top-Level
- Macro Transformation Errors, Lexical Analyser
- I/O, Operating System, External Interface
- Debugging, Object Files
- Extensions

### C.1.1 Argument Types and Values

Event | Event Type | Default Event Handler
1 | general error | error_handler / 2
2 | term of an unknown type | error_handler / 2
4 | instantiation fault | error_handler / 4
5 | type error | error_handler / 4
6 | out of range | error_handler / 4
7 | string contains unexpected characters | error_handler / 2
8 | bad argument list | error_handler / 2

### C.1.2 Arithmetic, Environment

Event | Event Type | Default Event Handler
15 | creating parallel choice point | fail / 0
16 | failing to parallel choice point | fail / 0
17 | recomputation failed | error_handler / 2
20 | arithmetic exception | error_handler / 2
21 | undefined arithmetic expression | error_handler / 4
23 | comparison trap | compare_handler / 4
24 | number expected | error_handler / 2
25 | integer overflow | integer_overflow_handler / 2
30 | trying to write a read-only flag | error_handler / 2
31 | arity limit exceeded | error_handler / 2
32 | no handler for event | warning_handler / 2
33 | event queue overflow | error_handler / 2

### C.1.3 Data and Memory Areas, Predicates, Operators

Event | Event Type | Default Event Handler
40 | stale object handle | error_handler / 2
41 | array or global variable does not exist | undef_array_handler / 3
42 | redefining an existing array | make_array_handler / 4
43 | multiple definition postfix/infix | error_handler / 2
44 | record already exists | error_handler / 2
45 | record does not exist | undef_record_handler / 2
50 | trying to modify a read-only ground term | error_handler / 2
60 | referring to an undefined procedure | error_handler / 4
61 | inconsistent tool redefinition | error_handler / 4
62 | inconsistent procedure redefinition | error_handler / 4
63 | procedure not dynamic | error_handler / 4
64 | procedure already dynamic | dynamic_handler / 3
65 | procedure already defined | error_handler / 4
66 | trying to modify a system predicate | error_handler / 4
67 | procedure is not yet loaded | error_handler / 4
68 | calling an undefined procedure | call_handler / 4
69 | autoload event | autoload_handler / 4
70 | accessing an undefined dynamic procedure | undef_dynamic_handler / 3
71 | procedure already parallel | error_handler / 2
72 | accessing an undefined operator | error_handler / 2
73 | redefining an existing operator | true / 0
74 | hiding an existing global operator | true / 0
75 | referring to a deprecated predicate | declaration_warning_handler / 3
76 | predicate declared but not defined | declaration_warning_handler / 3
77 | predicate used but not declared or defined | declaration_warning_handler / 3
78 | calling a procedure with a reserved name | error_handler / 2

### C.1.4 Modules, Visibility

Event | Event Type | Default Event Handler
80 | not a module | error_handler / 2
81 | module/1 can appear only as a directive | error_handler / 2
82 | trying to access a locked module | locked_access_handler / 2
83 | creating a new module | warning_handler / 2
84 | referring to non-exported predicate | declaration_warning_handler / 3
85 | referring to non-existing module | declaration_warning_handler / 3
86 | lookup module does not exist | no_lookup_module_handler / 4
87 | attempt to redefine an existing local item | warning_handler / 3
88 | attempt to redefine an existing exported item | warning_handler / 3
89 | attempt to redefine an already imported item | warning_handler / 3
90 | procedure is already reexported | error_handler / 4
91 | not a tool procedure | error_handler / 2
92 | trying to redefine an existing local procedure | error_handler / 4
93 | trying to redefine an existing exported procedure | error_handler / 4
94 | trying to redefine an existing imported procedure | error_handler / 4
96 | ambiguous import | ambiguous_import_resolve / 3
97 | module already exists | error_handler / 2
98 | key not correct | error_handler / 2
99 | unresolved ambiguous import | ambiguous_import_warn / 3
100 | accessing a procedure defined in another module | undef_dynamic_handler / 3
101 | trying to erase a module from itself | error_handler / 2

### C.1.5 Syntax Errors, Parsing

Event | Event Type | Default Event Handler
110 | syntax error: | parser_error_handler / 2
111 | syntax error: list tail ended improperly | parser_error_handler / 2
112 | syntax error: illegal character in a quoted token | parser_error_handler / 2
113 | syntax error: unexpected comma | parser_error_handler / 2
114 | syntax error: unexpected token | parser_error_handler / 2
115 | syntax error: unexpected end of file | parser_error_handler / 2
116 | syntax error: numeric constant out of range | parser_error_handler / 2
117 | syntax error: bracket necessary | parser_error_handler / 2
118 | syntax error: unexpected fullstop | parser_error_handler / 2
119 | syntax error: postfix/infix operator expected | parser_error_handler / 2
120 | syntax error: wrong solo char | parser_error_handler / 2
121 | syntax error: space between functor and open bracket | parser_error_handler / 2
122 | syntax error: variable with multiple attributes | parser_error_handler / 2
123 | illegal iteration specifier in do-loop | error_handler / 4
124 | syntax error : prefix operator followed by infix operator | parser_error_handler / 2
125 | syntax error : unexpected closing bracket | parser_error_handler / 2
126 | syntax error : grammar rule head is not valid | parser_error_handler / 2
127 | syntax error : grammar rule body is not valid | parser_error_handler / 2
128 | syntax error : in source transformation | parser_error_handler / 2
129 | syntax error: source transformation floundered | parser_error_handler / 2

### C.1.6 Compilation, Run-Time System, Execution

Event | Event Type | Default Event Handler
130 | syntax error: illegal head | compiler_error_handler / 2
131 | syntax error: illegal goal | compiler_error_handler / 2
132 | syntax error: term of an unknown type | compiler_error_handler / 2
133 | loading the library | true / 0
134 | procedure clauses are not consecutive | compiler_error_handler / 2
135 | trying to redefine a protected procedure | compiler_error_handler / 2
136 | trying to redefine a built-in predicate | compiler_error_handler / 2
137 | trying to redefine a procedure with another type | compiler_error_handler / 2
138 | singleton local variable in do-loop | singleton_in_loop / 2
139 | compiled or dumped file message | compiled_file_handler / 3
140 | undefined instruction | error_handler / 2
141 | unimplemented functionality | error_handler / 2
142 | built-in predicate not available on this system | error_handler / 2
143 | compiled query failed | compiler_error_handler / 2
144 | a cut is not allowed in a condition | compiler_error_handler / 2
145 | procedure being redefined in another file | redef_other_file_handler / 2
146 | start of compilation | true / 0
147 | compilation aborted | compiler_abort_handler / 3
148 | bad pragma | pragma_handler / 3
149 | code unit loaded | unit_loaded_handler / 3

The handlers for these events receive the following arguments:

Event | Second Argument | Third Argument
130 | Culprit clause | Module
131 | Culprit clause | Module
132 | Culprit clause | Module
133 | Library name (string) | undefined
134 | Procedure Name/Arity | Module
135 | Procedure Name/Arity | Module
136 | Procedure Name/Arity | Module
137 | Procedure Name/Arity | Module
138 | Variable name (atom) | undefined
139 | (File, Size, Time), see below | Module
140 | ’Emulate’ | undefined
141 | Goal | Module
142 | Goal | Module
143 | Goal | Module
144 | Goal (if an execution error) or Culprit clause (if compiler error) | Module
145 | (Name/Arity, OldFile, NewFile) | Module
146 | File | Module
147 | File
148 | Clause | Module

The second argument for the event 139 depends on the predicate where it was raised:

- compile/1,2 - (file name, code size, compile time)
- compile_stream/1 - (’string’, code size, compile time) with a string stream
- compile_stream/1 - (file name, code size, compile time) with a stream associated to a file

### C.1.7 Top-Level

Event | Event Type | Default Event Handler
150 | start of eclipse execution | sepia_start / 0
151 | eclipse restart | true / 0
152 | end of eclipse execution | sepia_end / 0
153 | toplevel: print prompt | toplevel_prompt / 2
154 | toplevel: start of query execution | true / 0
155 | toplevel: print values | print_values / 3
156 | toplevel: print answer | tty_ask_more / 2
157 | error exit | error_exit / 0
158 | toplevel: entering break level | start_break / 3
159 | toplevel: leaving break level | end_break / 3

These events are not errors but rather hooks to allow users to modify the behaviour of the ECLiPSe toplevel. Therefore the arguments that are passed to the handler are not the erroneous goal and the caller module but defined as follows:

Event | Second Argument | Third Argument
150 | A free variable. If the handler binds the variable to an atom, this name is used as the toplevel module name | undefined
151 | undefined | undefined
152 | The argument is the number that ECLiPSe will return to the operating system | undefined
153 | current toplevel module | current toplevel module
154 | a structure of the form goal(Goal, VarList, NewGoal, NewVarList), where Goal is the goal that is about to be executed and VarList is the list that associates the variables in Goal with their names (like in readvar/3). NewGoal and NewVarList are free variables. If the handler binds NewVarList then the toplevel will use NewGoal and NewVarList to replace Goal and VarList in the current query. | current toplevel module

Event | Second Argument | Third Argument
155 | A list associating the variable names with their values after the query has been executed. | current toplevel module
156 | An atom stating the answer to the query that was just executed. The possible values are: yes, last_yes or no if the query had no variables, more_answers, last_answer if the query contained variables and bindings were printed, no_answer if a query containing variables failed. | current toplevel module
157 | undefined | undefined
158 | break level | current toplevel module
159 | break level | current toplevel module

When the handler for event 152 (“end of eclipse execution”) calls throw/1, ECLiPSe is not exited. This is a way to prevent accidental exits from the system. Failure of the handler is ignored.

### C.1.8 Macro Transformation Errors, Lexical Analyser

Event | Event Type | Default Event Handler
160 | global macro transformation already exists | error_handler / 4
161 | macro transformation already defined in this module | macro_handler / 3
162 | no macro transformation defined in this module | warning_handler / 2
163 | illegal attempt to remove the last member of a character class | error_handler / 2
164 | toplevel: print banner | tty_banner / 2
165 | can’t compile an attributed variable (use add_attribute/2,3) | error_handler / 2
166 | file successfully processed | record_compiled_file_handler / 3
167 | initialization/finalization goal failed or aborted | warning_handler / 3

The event 164 is raised whenever the toplevel loop is restarted.

Event | Second Argument | Third Argument
164 | the banner string

### C.1.9 I/O, Operating System, External Interface

Event | Event Type | Default Event Handler
170 | system interface error | system_error_handler / 4
171 | File does not exist : | error_handler / 2
172 | File is not open : | error_handler / 2
173 | library not found | error_handler / 2
174 | child process terminated due to signal | error_handler / 2
175 | child process stopped | error_handler / 2
176 | message passing error | error_handler / 2
177 | shared library not found | error_handler / 2
190 | end of file reached | eof_handler / 4
191 | output error | output_error_handler / 4
192 | illegal stream mode | error_handler / 2
193 | illegal stream specification | error_handler / 2
194 | too many symbolic names of a stream | error_handler / 2
195 | yield on flush | io_yield_handler / 2
196 | trying to modify a system stream | close_handler / 2
197 | use ’input’ or ’output’ instead of ’user’ | error_handler / 2
198 | reading past the file end | past_eof_handler / 2
210 | Remember() not inside a backtracking predicate | error_handler / 2
211 | External function does not exist | error_handler / 2
212 | External function returned invalid code | error_handler / 2
213 | Error in external function | error_handler / 2
214 | Licensing problem | error_handler / 2

### C.1.10 Debugging, Object Files

Event | Event Type | Default Event Handler
230 | uncaught exception | error_handler / 2
231 | default help/0 message | fail / 0
249 | debugger new suspensions event | bip_delay / 0
250 | debugger init event | trace_start_handler_tty / 0
251 | debugger builtin fail event | bip_port / 4
252 | debugger port event | trace_line_handler_tty / 2
253 | debugger call event | ncall / 2
254 | debugger exit event | nexit / 1
255 | debugger redo event | redo / 5
256 | debugger delay event | ndelay / 2
257 | debugger wake event | resume / 2
258 | debugger builtin call event | bip_port / 4
259 | debugger builtin exit event | bip_port / 4
260 | unexpected end of file | error_handler / 2
261 | invalid saved state | error_handler / 2
262 | can not allocate required space | error_handler / 2
263 | can not save or restore from another break level than level 0 | error_handler / 2
264 | not an eclipse object file | compiled_file_handler / 3
265 | bad eclipse object file version | compiled_file_handler / 3
267 | predicate not implemented in this version | error_handler / 2
268 | predicate not supported in parallel session | error_handler / 2

These handlers receive special arguments:

Event | Second Argument | Third Argument
252 | trace_line{port:Port,frame:Frame} | undefined
264 | (File, [], []) | undefined
265 | (File, [], []) | undefined

### C.1.11 Extensions

Event | Event Type | Default Event Handler
270 | undefined variable attribute | error_handler / 2
271 | bad format of the variable attribute | error_handler / 2
272 | delay clause may cause indefinite delay | warning_handler / 2
273 | delayed goals left | delayed_goals_handler / 3
274 | stack of woken lists empty | error_handler / 2
280 | Found a solution with cost | cost_handler / 2

The handlers for these events receive the following arguments:

Event | Second Argument | Third Argument
272 | Culprit clause | Module
273 | list of sleeping suspensions | undefined
280 | Cost, Goal | undefined