Handle run-time errors

Syntax1 - on error, continue

err[+]

 

Syntax2 - on error, execute code and continue

err[+]
(tab)statements
(tab)...

 

Can be in single line:

err[+] statements

 

Syntax3 - the beginning of code guarded by err+

err-

 

Parameters

Options:

Default Handle errors of the preceding statement.
+ Handle errors of all preceding statements (or all preceding statements below err-).
- Marks the beginning of the block of statements guarded by err+.

 

Remarks

Use err to continue macro execution when a run-time error occurs.

 

When an error occurs:

 

Syntax2: On error executes statements. If no error, skips statements.

 

err handles errors generated by QM functions, user-defined functions (see end) , COM functions and the OS (exceptions). It does not handle some non-continuable errors, such as "noncompiled function", "failed constructor". It is not used to handle compile-time errors.

 

When an error occurs, special variable _error is filled with information about the error.

 

type QMERROR ~description code iid source place ~line

 

description - string that you can see in QM output when error is generated and not handled.

code - a numeric value that can be used to identify the error. Can be 0.

iid - id of QM item where the error is generated.

source - one of: 0 - no error, 1 - compile-time error, 2 - run-time error generated by QM, 3 - run-time error generated by end, 4 - exception.

place - offset of the statement in macro text. In sub-functions it it is relative to parent text.

line - the statement (text). Not available in exe (empty).

 

_error has thread scope, that is, is accessible in all functions of that thread, including functions registered to run when thread ends (atend). In a function registered by atend, _error contains error info if the thread ended due to an error; it is empty (source is 0) if no error.

 

err handles errors generated in current macro/function only. It does not handle errors generated in user-defined functions that are called from current macro/function. However called functions can pass their errors to the caller. There are two ways: 1. Add opt noerrorshere 1 somewhere at the beginning (new in QM 2.3.5). 2. Add err+ end _error at the end (you can also add more code before end).

 

To see possible errors, check menu Run -> Compiler Options -> Show possible run-time errors. Then, when you compile a macro (click Run or Compile button), it shows functions that may throw errors when the macro runs. It adds indicators in the code editor. You can Alt+click an indicator to show the errors in QM output. This feature helps you to decide where to use err. Does not show some errors.

 

See also: Common errors, opt err, opt noerrorshere, opt nowarningshere, error constants

 

Examples

 Close "Notepad" window; ignore possible error (on error don't end macro):
clo "Notepad"; err

 Activate "Notepad" window; on error display error description:
act "Notepad"
err
	out _error.description

 Handle errors of all preceding statements and generate them in caller:
err+ end _error

__________________________________

 Loop example:

out
run "$system$\notepad.exe"
1
int i
for i 0 3
	out "activate Notepad"
	act "Notepad" ;;throws error if Notepad not found
	err ;;handles the error
		out _error.description
		continue
	out "close Notepad"
	clo "Notepad"

__________________________________

 If macro ends due to an error, log the error to file 'My Documents\My QM\qm log.txt':

 Insert this at the beginning of each macro that needs error logging:
atend LogErrors

 And create function LogErrors:
if(_error.source) ;;macro ended due to an error
	str macroname.getmacro(getopt(itemid 3) 1)
	str functionname.getmacro(_error.iid 1)
	LogFile F"Macro {macroname}: error in {functionname}.[]Error description: {_error.description}[]Error line: {_error.line}[]" 1