|
2679
|
1 @c Copyright (C) 1996, 1997 John W. Eaton |
|
|
2 @c This is part of the Octave manual. |
|
|
3 @c For copying conditions, see the file gpl.texi. |
|
|
4 |
|
|
5 @node Error Handling, Input and Output, Functions and Scripts, Top |
|
|
6 @chapter Error Handling |
|
|
7 |
|
2689
|
8 Octave includes several functions for printing error and warning |
|
|
9 messages. When you write functions that need to take special action |
|
|
10 when they encounter abnormal conditions, you should print the error |
|
|
11 messages using the functions described in this chapter. |
|
|
12 |
|
2679
|
13 @deftypefn {Built-in Function} {} error (@var{template}, @dots{}) |
|
|
14 The @code{error} function formats the optional arguments under the |
|
|
15 control of the template string @var{template} using the same rules as |
|
|
16 the @code{printf} family of functions (@pxref{Formatted Output}). |
|
|
17 The resulting message is prefixed by the string @samp{error: } and |
|
|
18 printed on the @code{stderr} stream. |
|
|
19 |
|
|
20 Calling @code{error} also sets Octave's internal error state such that |
|
|
21 control will return to the top level without evaluating any more |
|
|
22 commands. This is useful for aborting from functions or scripts. |
|
|
23 |
|
|
24 If the error message does not end with a new line character, Octave will |
|
|
25 print a traceback of all the function calls leading to the error. For |
|
|
26 example, given the following function definitions: |
|
|
27 |
|
|
28 @example |
|
|
29 @group |
|
|
30 function f () g () end |
|
|
31 function g () h () end |
|
|
32 function h () nargin == 1 || error ("nargin != 1"); end |
|
|
33 @end group |
|
|
34 @end example |
|
|
35 |
|
|
36 @noindent |
|
|
37 calling the function @code{f} will result in a list of messages that |
|
|
38 can help you to quickly locate the exact location of the error: |
|
|
39 |
|
|
40 @example |
|
|
41 @group |
|
|
42 f () |
|
|
43 error: nargin != 1 |
|
|
44 error: evaluating index expression near line 1, column 30 |
|
|
45 error: evaluating binary operator `||' near line 1, column 27 |
|
|
46 error: called from `h' |
|
|
47 error: called from `g' |
|
|
48 error: called from `f' |
|
|
49 @end group |
|
|
50 @end example |
|
|
51 |
|
|
52 If the error message ends in a new line character, Octave will print the |
|
|
53 message but will not display any traceback messages as it returns |
|
|
54 control to the top level. For example, modifying the error message |
|
|
55 in the previous example to end in a new line causes Octave to only print |
|
|
56 a single message: |
|
|
57 |
|
|
58 @example |
|
|
59 @group |
|
|
60 function h () nargin == 1 || error ("nargin != 1\n"); end |
|
|
61 f () |
|
|
62 error: nargin != 1 |
|
|
63 @end group |
|
|
64 @end example |
|
|
65 @end deftypefn |
|
|
66 |
|
|
67 @defvr {Built-in Variable} error_text |
|
3156
|
68 This variable contains the text of error messages that would have |
|
2679
|
69 been printed in the body of the most recent @code{unwind_protect} or |
|
|
70 @code{try} statement or the @var{try} part of the most recent call to |
|
|
71 the @code{eval} function. Outside of the @code{unwind_protect} and |
|
|
72 @code{try} statements or the @code{eval} function, or if no error has |
|
2689
|
73 occurred within them, the value of @code{error_text} is guaranteed to be |
|
2679
|
74 the empty string. |
|
|
75 |
|
|
76 Note that the message does not include the first @samp{error: } prefix, |
|
|
77 so that it may easily be passed to the @code{error} function without |
|
|
78 additional processing@footnote{Yes, it's a kluge, but it seems to be a |
|
|
79 reasonably useful one.}. |
|
|
80 |
|
|
81 @xref{The try Statement} and @ref{The unwind_protect Statement}. |
|
|
82 @end defvr |
|
|
83 |
|
|
84 @defvr {Built-in Variable} beep_on_error |
|
|
85 If the value of @code{beep_on_error} is nonzero, Octave will try |
|
|
86 to ring your terminal's bell before printing an error message. The |
|
|
87 default value is 0. |
|
|
88 @end defvr |
|
|
89 |
|
|
90 @deftypefn {Built-in Function} {} warning (@var{msg}) |
|
2689
|
91 Print a warning message @var{msg} prefixed by the string @samp{warning: }. |
|
|
92 After printing the warning message, Octave will continue to execute |
|
|
93 commands. You should use this function should when you want to notify |
|
|
94 the user of an unusual condition, but only when it makes sense for your |
|
|
95 program to go on. |
|
2679
|
96 @end deftypefn |
|
|
97 |
|
|
98 @deftypefn {Built-in Function} {} usage (@var{msg}) |
|
|
99 Print the message @var{msg}, prefixed by the string @samp{usage: }, and |
|
|
100 set Octave's internal error state such that control will return to the |
|
|
101 top level without evaluating any more commands. This is useful for |
|
|
102 aborting from functions. |
|
|
103 |
|
|
104 After @code{usage} is evaluated, Octave will print a traceback of all |
|
|
105 the function calls leading to the usage message. |
|
2689
|
106 |
|
|
107 You should use this function for reporting problems errors that result |
|
|
108 from an improper call to a function, such as calling a function with an |
|
|
109 incorrect number of arguments, or with arguments of the wrong type. For |
|
|
110 example, most functions distributed with Octave begin with code like |
|
|
111 this |
|
|
112 |
|
|
113 @example |
|
|
114 @group |
|
|
115 if (nargin != 2) |
|
|
116 usage ("foo (a, b)"); |
|
|
117 endif |
|
|
118 @end group |
|
|
119 @end example |
|
|
120 |
|
|
121 @noindent |
|
|
122 to check for the proper number of arguments. |
|
2679
|
123 @end deftypefn |
|
|
124 |
|
|
125 The following pair of functions are of limited usefulness, and may be |
|
|
126 removed from future versions of Octave. |
|
|
127 |
|
|
128 @deftypefn {Function File} {} perror (@var{name}, @var{num}) |
|
|
129 Print the error message for function @var{name} corresponding to the |
|
|
130 error number @var{num}. This function is intended to be used to print |
|
|
131 useful error messages for those functions that return numeric error |
|
|
132 codes. |
|
|
133 @end deftypefn |
|
|
134 |
|
|
135 @deftypefn {Function File} {} strerror (@var{name}, @var{num}) |
|
|
136 Return the text of an error message for function @var{name} |
|
|
137 corresponding to the error number @var{num}. This function is intended |
|
|
138 to be used to print useful error messages for those functions that |
|
|
139 return numeric error codes. |
|
|
140 @end deftypefn |
