1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>AARM95 - The Package Exceptions</TITLE>
<META NAME="Author" CONTENT="JTC1/SC22/WG9/ARG, by Randall Brukardt, ARG Editor">
<META NAME="GENERATOR" CONTENT="Arm_Form.Exe, Ada Reference Manual generator">
<STYLE type="text/css">
DIV.paranum {position: absolute; font-family: Arial, Helvetica, sans-serif; left: 0.5 em; top: auto}
TT {font-family: "Courier New", monospace}
DT {display: compact}
DIV.Normal {font-family: "Times New Roman", Times, serif; margin-bottom: 0.6em}
DIV.Wide {font-family: "Times New Roman", Times, serif; margin-top: 0.6em; margin-bottom: 0.6em}
DIV.Annotations {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-bottom: 0.6em}
DIV.WideAnnotations {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-top: 0.6em; margin-bottom: 0.6em}
DIV.Index {font-family: "Times New Roman", Times, serif}
DIV.SyntaxSummary {font-family: "Times New Roman", Times, serif; margin-left: 2.0em; margin-bottom: 0.4em}
DIV.Notes {font-family: "Times New Roman", Times, serif; margin-left: 2.0em; margin-bottom: 0.6em}
DIV.NotesHeader {font-family: "Times New Roman", Times, serif; margin-left: 2.0em}
DIV.SyntaxIndented {font-family: "Times New Roman", Times, serif; margin-left: 2.0em; margin-bottom: 0.4em}
DIV.Indented {font-family: "Times New Roman", Times, serif; margin-left: 6.0em; margin-bottom: 0.6em}
DIV.CodeIndented {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-bottom: 0.6em}
DIV.SmallIndented {font-family: "Times New Roman", Times, serif; margin-left: 10.0em; margin-bottom: 0.6em}
DIV.SmallCodeIndented {font-family: "Times New Roman", Times, serif; margin-left: 8.0em; margin-bottom: 0.6em}
DIV.Examples {font-family: "Courier New", monospace; margin-left: 2.0em; margin-bottom: 0.6em}
DIV.SmallExamples {font-family: "Courier New", monospace; font-size: 80%; margin-left: 7.5em; margin-bottom: 0.6em}
DIV.IndentedExamples {font-family: "Courier New", monospace; margin-left: 8.0em; margin-bottom: 0.6em}
DIV.SmallIndentedExamples {font-family: "Courier New", monospace; font-size: 80%; margin-left: 15.0em; margin-bottom: 0.6em}
UL.Bulleted {font-family: "Times New Roman", Times, serif; margin-left: 2.0em; margin-right: 2.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.SmallBulleted {font-family: "Times New Roman", Times, serif; margin-left: 6.0em; margin-right: 6.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.NestedBulleted {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-right: 4.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.SmallNestedBulleted {font-family: "Times New Roman", Times, serif; margin-left: 8.0em; margin-right: 8.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.IndentedBulleted {font-family: "Times New Roman", Times, serif; margin-left: 8.0em; margin-right: 8.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.CodeIndentedBulleted {font-family: "Times New Roman", Times, serif; margin-left: 6.0em; margin-right: 6.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.CodeIndentedNestedBulleted {font-family: "Times New Roman", Times, serif; margin-left: 8.0em; margin-right: 8.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.SyntaxIndentedBulleted {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-right: 4.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.NotesBulleted {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-right: 4.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.NotesNestedBulleted {font-family: "Times New Roman", Times, serif; margin-left: 6.0em; margin-right: 6.0em; margin-top: 0em; margin-bottom: 0.5em}
DL.Hanging {font-family: "Times New Roman", Times, serif; margin-top: 0em; margin-bottom: 0.6em}
DD.Hanging {margin-left: 6.0em}
DL.IndentedHanging {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-top: 0em; margin-bottom: 0.6em}
DD.IndentedHanging {margin-left: 2.0em}
DL.HangingInBulleted {font-family: "Times New Roman", Times, serif; margin-left: 2.0em; margin-right: 2.0em; margin-top: 0em; margin-bottom: 0.5em}
DD.HangingInBulleted {margin-left: 4.0em}
DL.SmallHanging {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-top: 0em; margin-bottom: 0.6em}
DD.SmallHanging {margin-left: 7.5em}
DL.SmallIndentedHanging {font-family: "Times New Roman", Times, serif; margin-left: 8.0em; margin-top: 0em; margin-bottom: 0.6em}
DD.SmallIndentedHanging {margin-left: 2.0em}
DL.SmallHangingInBulleted {font-family: "Times New Roman", Times, serif; margin-left: 6.0em; margin-right: 6.0em; margin-top: 0em; margin-bottom: 0.5em}
DD.SmallHangingInBulleted {margin-left: 5.0em}
DL.Enumerated {font-family: "Times New Roman", Times, serif; margin-right: 0.0em; margin-top: 0em; margin-bottom: 0.5em}
DD.Enumerated {margin-left: 2.0em}
DL.SmallEnumerated {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-right: 4.0em; margin-top: 0em; margin-bottom: 0.5em}
DD.SmallEnumerated {margin-left: 2.5em}
DL.NestedEnumerated {font-family: "Times New Roman", Times, serif; margin-left: 2.0em; margin-right: 2.0em; margin-top: 0em; margin-bottom: 0.5em}
DL.SmallNestedEnumerated {font-family: "Times New Roman", Times, serif; margin-left: 6.0em; margin-right: 6.0em; margin-top: 0em; margin-bottom: 0.5em}
</STYLE>
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#FFFFF0" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
<P><A HREF="AA-TOC.html">Contents</A> <A HREF="AA-0-29.html">Index</A> <A HREF="AA-11-4.html">Previous</A> <A HREF="AA-11-4-2.html">Next</A></P>
<HR>
<H1> 11.4.1 The Package Exceptions</H1>
<H4 ALIGN=CENTER>Static Semantics</H4>
<DIV Class="Paranum"><FONT SIZE=-2>1</FONT></DIV>
<DIV Class="Normal" Style="margin-bottom: 0.4em"> The following language-defined
library package exists: </DIV>
<DIV Class="Paranum"><FONT SIZE=-2>2</FONT></DIV>
<DIV Class="Examples"><TT><A NAME="I4075"></A><A NAME="I4076"></A><A NAME="I4077"></A><BR>
<B>package</B> Ada.Exceptions <B>is</B><BR>
<B>type</B> <A NAME="I4078"></A><A NAME="I4079"></A>Exception_Id <B>is</B> <B>private</B>;<BR>
<A NAME="I4080"></A>Null_Id : <B>constant</B> Exception_Id;<BR>
<B>function</B> <A NAME="I4081"></A><A NAME="I4082"></A>Exception_Name(Id : Exception_Id) <B>return</B> String;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>3</FONT></DIV>
<DIV Class="Examples"><TT> <B>type</B> <A NAME="I4083"></A><A NAME="I4084"></A>Exception_Occurrence <B>is</B> <B>limited</B> <B>private</B>;<BR>
<B>type</B> <A NAME="I4085"></A><A NAME="I4086"></A>Exception_Occurrence_Access <B>is</B> <B>access</B> <B>all</B> Exception_Occurrence;<BR>
<A NAME="I4087"></A>Null_Occurrence : <B>constant</B> Exception_Occurrence;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>4</FONT></DIV>
<DIV Class="Examples"><TT> <B>procedure</B> <A NAME="I4088"></A><A NAME="I4089"></A>Raise_Exception(E : <B>in</B> Exception_Id;<BR>
Message : <B>in</B> String := "");<BR>
<B>function</B> <A NAME="I4090"></A><A NAME="I4091"></A>Exception_Message(X : Exception_Occurrence) <B>return</B> String;<BR>
<B>procedure</B> <A NAME="I4092"></A><A NAME="I4093"></A>Reraise_Occurrence(X : <B>in</B> Exception_Occurrence);</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>5</FONT></DIV>
<DIV Class="Examples"><TT> <B>function</B> <A NAME="I4094"></A><A NAME="I4095"></A>Exception_Identity(X : Exception_Occurrence)<BR>
<B>return</B> Exception_Id;<BR>
<B>function</B> <A NAME="I4096"></A><A NAME="I4097"></A>Exception_Name(X : Exception_Occurrence) <B>return</B> String;<BR>
--<I> Same as Exception_Name(Exception_Identity(X)).</I><BR>
<B>function</B> <A NAME="I4098"></A><A NAME="I4099"></A>Exception_Information(X : Exception_Occurrence) <B>return</B> String;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>6</FONT></DIV>
<DIV Class="Examples"><TT> <B>procedure</B> <A NAME="I4100"></A><A NAME="I4101"></A>Save_Occurrence(Target : <B>out</B> Exception_Occurrence;<BR>
Source : <B>in</B> Exception_Occurrence);<BR>
<B>function</B> <A NAME="I4102"></A><A NAME="I4103"></A>Save_Occurrence(Source : Exception_Occurrence)<BR>
<B>return</B> Exception_Occurrence_Access;<BR>
<B>private</B><BR>
... --<I> not specified by the language</I><BR>
<B>end</B> Ada.Exceptions;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>7</FONT></DIV>
<DIV Class="Normal"> Each distinct exception is represented by a distinct
value of type Exception_Id. Null_Id does not represent any exception,
and is the default initial value of type Exception_Id. Each occurrence
of an exception is represented by a value of type Exception_Occurrence.
Null_Occurrence does not represent any exception occurrence, and is the
default initial value of type Exception_Occurrence.</DIV>
<DIV Class="Paranum"><FONT SIZE=-2>8/1</FONT></DIV>
<DIV Class="Normal" Style="margin-bottom: 0.4em"> For a <U><FONT FACE="Arial, Helvetica">prefix</FONT></U><S>prefix</S>
E that denotes an exception, the following attribute is defined: </DIV>
<DIV Class="Paranum"><FONT SIZE=-2>9</FONT></DIV>
<DL Class="Hanging"><DT> E'Identity<DD Class="Hanging">
<A NAME="I4104"></A><A NAME="I4105"></A>E'Identity returns the unique
identity of the exception. The type of this attribute is Exception_Id.
</DL>
<DIV Class="Paranum"><FONT SIZE=-2>9.a</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Ramification: </B>In a distributed
program, the identity is unique across an entire program, not just across
a single partition. Exception propagation works properly across RPC's.
An exception can be propagated from one partition to another, and then
back to the first, where its identity is known. </FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>10</FONT></DIV>
<DIV Class="Normal"> Raise_Exception raises a new occurrence of the
identified exception. In this case, Exception_Message returns the Message
parameter of Raise_Exception. For a <FONT FACE="Arial, Helvetica">raise_statement</FONT>
with an <I>exception_</I><FONT FACE="Arial, Helvetica">name</FONT>, Exception_Message
returns implementation-defined information about the exception occurrence.
Reraise_Occurrence reraises the specified exception occurrence. </DIV>
<DIV Class="Paranum"><FONT SIZE=-2>10.a</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Implementation defined: </B>The
information returned by Exception_Message.</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>10.b</FONT></DIV>
<DIV Class="Annotations" Style="margin-bottom: 0.4em"><FONT SIZE=-1><B>Ramification:
</B>Given an exception E, the <FONT FACE="Arial, Helvetica">raise_statement</FONT>:
</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>10.c</FONT></DIV>
<DIV Class="SmallExamples"><TT><B>raise</B> E;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>10.d</FONT></DIV>
<DIV Class="WideAnnotations" Style="margin-bottom: 0.4em"><FONT SIZE=-1>is
equivalent to this call to Raise_Exception: </FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>10.e</FONT></DIV>
<DIV Class="SmallExamples"><TT>Raise_Exception(E'Identity, Message => <I>implementation-defined-string</I>);</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>10.f</FONT></DIV>
<DIV Class="WideAnnotations" Style="margin-bottom: 0.4em"><FONT SIZE=-1>The
following handler: </FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>10.g</FONT></DIV>
<DIV Class="SmallExamples"><TT><B>when</B> <B>others</B> =><BR>
Cleanup;<BR>
<B>raise</B>;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>10.h</FONT></DIV>
<DIV Class="WideAnnotations" Style="margin-bottom: 0.4em"><FONT SIZE=-1>is
equivalent to this one: </FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>10.i</FONT></DIV>
<DIV Class="SmallExamples"><TT><B>when</B> X : <B>others</B> =><BR>
Cleanup;<BR>
Reraise_Occurrence(X);</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>11</FONT></DIV>
<DIV Class="Normal"> Exception_Identity returns the identity of the
exception of the occurrence.</DIV>
<DIV Class="Paranum"><FONT SIZE=-2>12</FONT></DIV>
<DIV Class="Normal"> The Exception_Name functions return the full
expanded name of the exception, in upper case, starting with a root library
unit. For an exception declared immediately within package Standard,
the <FONT FACE="Arial, Helvetica">defining_identifier</FONT> is returned.
The result is implementation defined if the exception is declared within
an unnamed <FONT FACE="Arial, Helvetica">block_statement</FONT>. </DIV>
<DIV Class="Paranum"><FONT SIZE=-2>12.a</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Ramification: </B>See the Implementation
Permission below. </FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>12.b</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>To be honest: </B>This name,
as well as each <FONT FACE="Arial, Helvetica">prefix</FONT> of it, does
not denote a <FONT FACE="Arial, Helvetica">renaming_declaration</FONT>.
</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>12.c</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Implementation defined: </B>The
result of Exceptions.Exception_Name for types declared within an unnamed
<FONT FACE="Arial, Helvetica">block_statement</FONT>.</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>12.d</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Ramification: </B>Note that
we're talking about the name of the exception, not the name of the occurrence.
</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>13</FONT></DIV>
<DIV Class="Normal"> Exception_Information returns implementation-defined
information about the exception occurrence. </DIV>
<DIV Class="Paranum"><FONT SIZE=-2>13.a</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Implementation defined: </B>The
information returned by Exception_Information.</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>14</FONT></DIV>
<DIV Class="Normal"> Raise_Exception and Reraise_Occurrence have no
effect in the case of Null_Id or Null_Occurrence. <A NAME="I4106"></A>Exception_Message,
Exception_Identity, Exception_Name, and Exception_Information raise Constraint_Error
for a Null_Id or Null_Occurrence.</DIV>
<DIV Class="Paranum"><FONT SIZE=-2>15</FONT></DIV>
<DIV Class="Normal"> The Save_Occurrence procedure copies the Source
to the Target. The Save_Occurrence function uses an <FONT FACE="Arial, Helvetica">allocator</FONT>
of type Exception_Occurrence_Access to create a new object, copies the
Source to this new object, and returns an access value designating this
new object; [the result may be deallocated using an instance of Unchecked_Deallocation.]
</DIV>
<DIV Class="Paranum"><FONT SIZE=-2>15.a</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Ramification: </B>It's OK to
pass Null_Occurrence to the Save_Occurrence subprograms; they don't raise
an exception, but simply save the Null_Occurrence. </FONT></DIV>
<H4 ALIGN=CENTER>Implementation Requirements</H4>
<DIV Class="Paranum"><FONT SIZE=-2>16</FONT></DIV>
<DIV Class="Normal"> The implementation of the Write attribute (see
<A HREF="AA-13-13-2.html">13.13.2</A>) of Exception_Occurrence shall
support writing a representation of an exception occurrence to a stream;
the implementation of the Read attribute of Exception_Occurrence shall
support reconstructing an exception occurrence from a stream (including
one written in a different partition). </DIV>
<DIV Class="Paranum"><FONT SIZE=-2>16.a</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Ramification: </B>The identity
of the exception, as well as the Exception_Name and Exception_Message,
have to be preserved across partitions.</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>16.b</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1>The string returned by Exception_Name
or Exception_Message on the result of calling the Read attribute on a
given stream has to be the same as the value returned by calling the
corresponding function on the exception occurrence that was written into
the stream with the Write attribute. The string returned by Exception_Information
need not be the same, since it is implementation defined anyway. </FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>16.c</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Reason: </B>This is important
for supporting writing exception occurrences to external files for post-mortem
analysis, as well as propagating exceptions across remote subprogram
calls in a distributed system (see <A HREF="AA-E-4.html">E.4</A>). </FONT></DIV>
<H4 ALIGN=CENTER>Implementation Permissions</H4>
<DIV Class="Paranum"><FONT SIZE=-2>17</FONT></DIV>
<DIV Class="Normal"> An implementation of Exception_Name in a space-constrained
environment may return the <FONT FACE="Arial, Helvetica">defining_identifier</FONT>
instead of the full expanded name.</DIV>
<DIV Class="Paranum"><FONT SIZE=-2>18</FONT></DIV>
<DIV Class="Normal"> The string returned by Exception_Message may
be truncated (to no less than 200 characters) by the Save_Occurrence
procedure [(not the function)], the Reraise_Occurrence procedure, and
the re-raise statement. </DIV>
<DIV Class="Paranum"><FONT SIZE=-2>18.a</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Reason: </B>The reason for
allowing truncation is to ease implementations. The reason for choosing
the number 200 is that this is the minimum source line length that implementations
have to support, and this feature seems vaguely related since it's usually
a ``one-liner''. Note that an implementation is allowed to do this truncation
even if it supports arbitrarily long lines. </FONT></DIV>
<H4 ALIGN=CENTER>Implementation Advice</H4>
<DIV Class="Paranum"><FONT SIZE=-2>19</FONT></DIV>
<DIV Class="Normal"> Exception_Message (by default) and Exception_Information
should produce information useful for debugging. Exception_Message should
be short (about one line), whereas Exception_Information can be long.
Exception_Message should not include the Exception_Name. Exception_Information
should include both the Exception_Name and the Exception_Message. </DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19.a</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Reason: </B>It may seem strange
to define two subprograms whose semantics is implementation defined.
The idea is that a program can print out debugging/error-logging information
in a portable way. The program is portable in the sense that it will
work in any implementation; it might print out different information,
but the presumption is that the information printed out is appropriate
for debugging/error analysis on that system. </FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19.b</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Implementation Note: </B>As
an example, Exception_Information might include information identifying
the location where the exception occurred, and, for predefined exceptions,
the specific kind of language-defined check that failed. There is an
implementation trade-off here, between how much information is represented
in an Exception_Occurrence, and how much can be passed through a re-raise.</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19.c</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1>The string returned should be
in a form suitable for printing to an error log file. This means that
it might need to contain line-termination control characters with implementation-defined
I/O semantics. The string should neither start nor end with a newline.</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19.d</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1>If an implementation chooses to
provide additional functionality related to exceptions and their occurrences,
it should do so by providing one or more children of Ada.Exceptions.</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19.e</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1>Note that exceptions behave as
if declared at library level; there is no ``natural scope'' for an exception;
an exception always exists. Hence, there is no harm in saving an exception
occurrence in a data structure, and reraising it later. The reraise has
to occur as part of the same program execution, so saving an exception
occurrence in a file, reading it back in from a different program execution,
and then reraising it is not required to work. This is similar to I/O
of access types. Note that it is possible to use RPC to propagate exceptions
across partitions.</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19.f</FONT></DIV>
<DIV Class="Annotations" Style="margin-bottom: 0.4em"><FONT SIZE=-1>Here's
one way to implement Exception_Occurrence in the private part of the
package. Using this method, an implementation need store only the actual
number of characters in exception messages. If the user always uses small
messages, then exception occurrences can be small. If the user never
uses messages, then exception occurrences can be smaller still: </FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19.g</FONT></DIV>
<DIV Class="SmallExamples"><TT><B>type</B> Exception_Occurrence(Message_Length : Natural := 200) <B>is</B><BR>
<B>limited</B> <B>record</B><BR>
Id : Exception_Id;<BR>
Message : String(1..Message_Length);<BR>
<B>end</B> <B>record</B>;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19.h</FONT></DIV>
<DIV Class="Annotations" Style="margin-bottom: 0.4em"><FONT SIZE=-1>At
the point where an exception is raised, an Exception_Occurrence can be
allocated on the stack with exactly the right amount of space for the
message -- none for an empty message. This is just like declaring a constrained
object of the type: </FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19.i</FONT></DIV>
<DIV Class="SmallExamples"><TT>Temp : Exception_Occurrence(10); --<I> for a 10-character message</I></TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19.j</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1>After finding the appropriate
handler, the stack can be cut back, and the Temp copied to the right
place. This is similar to returning an unknown-sized object from a function.
It is not necessary to allocate the maximum possible size for every Exception_Occurrence.
If, however, the user declares an Exception_Occurrence object, the discriminant
will be permanently set to 200. The Save_Occurrence procedure would then
truncate the Exception_Message. Thus, nothing is lost until the user
tries to save the occurrence. If the user is willing to pay the cost
of heap allocation, the Save_Occurrence function can be used instead.</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19.k</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1>Note that any arbitrary-sized
implementation-defined Exception_Information can be handled in a similar
way. For example, if the Exception_Occurrence includes a stack traceback,
a discriminant can control the number of stack frames stored. The traceback
would be truncated or entirely deleted by the Save_Occurrence procedure
-- as the implementation sees fit.</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19.l</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1>If the internal representation
involves pointers to data structures that might disappear, it would behoove
the implementation to implement it as a controlled type, so that assignment
can either copy the data structures or else null out the pointers. Alternatively,
if the data structures being pointed at are in a task control block,
the implementation could keep a unique sequence number for each task,
so it could tell when a task's data structures no longer exist.</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19.m</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1>Using the above method, heap space
is never allocated unless the user calls the Save_Occurrence function.</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19.n</FONT></DIV>
<DIV Class="Annotations" Style="margin-bottom: 0.4em"><FONT SIZE=-1>An
alternative implementation would be to store the message strings on the
heap when the exception is raised. (It could be the global heap, or it
could be a special heap just for this purpose -- it doesn't matter.)
This representation would be used only for choice parameters. For normal
user-defined exception occurrences, the Save_Occurrence procedure would
copy the message string into the occurrence itself, truncating as necessary.
Thus, in this implementation, Exception_Occurrence would be implemented
as a variant record: </FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19.o</FONT></DIV>
<DIV Class="SmallExamples"><TT><B>type</B> Exception_Occurrence_Kind <B>is</B> (Normal, As_Choice_Param);</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19.p</FONT></DIV>
<DIV Class="SmallExamples"><TT><B>type</B> Exception_Occurrence(Kind : Exception_Occurrence_Kind := Normal) <B>is</B><BR>
<B>limited</B> <B>record</B><BR>
<B>case</B> Kind <B>is</B><BR>
<B>when</B> Normal =><BR>
... --<I> space for 200 characters</I><BR>
<B>when</B> As_Choice_Param =><BR>
... --<I> pointer to heap string</I><BR>
<B>end</B> <B>case</B>;<BR>
<B>end</B> <B>record</B>;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19.q</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1>Exception_Occurrences created
by the run-time system during exception raising would be As_Choice_Param.
User-declared ones would be Normal -- the user cannot see the discriminant,
and so cannot set it to As_Choice_Param. The strings in the heap would
be freed upon completion of the handler.</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19.r</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1>This alternative implementation
corresponds to a heap-based implementation of functions returning unknown-sized
results.</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19.s</FONT></DIV>
<DIV Class="Annotations" Style="margin-bottom: 0.4em"><FONT SIZE=-1>One
possible implementation of Reraise_Occurrence is as follows: </FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19.t</FONT></DIV>
<DIV Class="SmallExamples"><TT><B>procedure</B> Reraise_Occurrence(X : <B>in</B> Exception_Occurrence) <B>is</B><BR>
<B>begin</B><BR>
Raise_Exception(Identity(X), Exception_Message(X));<BR>
<B>end</B> Reraise_Occurrence;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19.u</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1>However, some implementations
may wish to retain more information across a re-raise -- a stack traceback,
for example. </FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19.v</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Ramification: </B>Note that
Exception_Occurrence is a definite subtype. Hence, values of type Exception_Occurrence
may be written to an error log for later analysis, or may be passed to
subprograms for immediate error analysis. </FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19.w</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Implementation Note: </B>If
an implementation chooses to have a mode in which it supports non-Latin-1
characters in identifiers, then it needs to define what the above functions
return in the case where the name of an exception contains such a character.
</FONT></DIV>
<H4 ALIGN=CENTER>Extensions to Ada 83</H4>
<DIV Class="Paranum"><FONT SIZE=-2>19.x</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><A NAME="I4107"></A>The Identity
attribute of exceptions is new, as is the package Exceptions. </FONT></DIV>
<HR>
<P><A HREF="AA-TOC.html">Contents</A> <A HREF="AA-0-29.html">Index</A> <A HREF="AA-11-4.html">Previous</A> <A HREF="AA-11-4-2.html">Next</A> <A HREF="AA-TTL.html">Legal</A></P>
</BODY>
</HTML>
|
