-
Notifications
You must be signed in to change notification settings - Fork 7
Expand file tree
/
Copy pathutoutput.html
More file actions
233 lines (185 loc) · 7.89 KB
/
Copy pathutoutput.html
File metadata and controls
233 lines (185 loc) · 7.89 KB
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
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<!-- WARNING! This file is generated. -->
<!-- To alter documentation, edit files in src directory -->
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>utOutput Package</title>
<link rel="stylesheet" href="utplsql.css" type="text/css" />
<meta name="keywords" content="utPLSQL, PL\SQL, Unit Testing, Framework, Oracle" />
<meta name="description" content="Unit Testing PL\SQL" />
<meta name="title" content="utOutput Package" />
<meta name="author" content="Steven Feuerstein, Chris Rimmer, Patrick Barel and the utPLSQL Project" />
<meta name="copyright" content="(C) 2000-2005, 2014-2016 Steven Feuerstein, Chris Rimmer, Patrick Barel and the utPLSQL Project" />
</head>
<body>
<div class="purple_bar"><a href="index.html"><img src="utplsql.jpg" alt="utPLSQL logo" /></a></div>
<p>[ <a href="index.html">Home</a>
| <a href="started.html">Getting Started</a>
| <a href="buildpack.html">Build Test Packages</a>
| <a href="examples.html">Examples</a>
| <a href="userguide.html">User Guide</a>
| <a href="release.html">Release Notes</a>
| <a href="map.html">Document Map</a> ]</p>
<p><a href="utgen.html">< Previous Section: utGen Package</a> | <a href="utreceq.html">Next Section: utRecEq Package ></a></p>
<!-- Begin utPLSQL Body -->
<!-- $Id$ -->
<h1>utOutput Package</h1>
<p>This package contains the following procedures and functions:</p>
<table cellspacing="5">
<tr>
<td><a href="#Saving">utOutput.save</a></td>
<td><a href="#Saving">Turn on the 'save' flag</a></td>
</tr>
<tr>
<td><a href="#Saving">utOutput.nosave</a></td>
<td><a href="#Saving">Turn off the 'save' flag</a></td>
</tr>
<tr>
<td><a href="#Saving">utOutput.saving</a></td>
<td><a href="#Saving">Return the 'save' flag</a></td>
</tr>
<tr>
<td><a href="#Extract">utOutput.extract</a></td>
<td><a href="#Extract">Pull text from the DBMS_OUTPUT buffer</a></td>
</tr>
<tr>
<td><a href="#Replace">utOutput.replace</a></td>
<td><a href="#Replace">Replace saved output in the DBMS_OUTPUT buffer</a></td>
</tr>
<tr>
<td><a href="#NextLine">utOutput.nextLine</a></td>
<td><a href="#NextLine">Pull the next line from the DBMS_OUTPUT buffer</a></td>
</tr>
<tr>
<td><a href="#Count">utOutput.count</a></td>
<td><a href="#Count">Count the lines in the DBMS_OUTPUT buffer</a></td>
</tr>
</table>
<h2>Outline of Usage</h2>
<p>
The problem with attempting to test output in PL/SQL is that there is a single
DBMS_OUTPUT buffer. When your test is run, there may already be output in the
buffer from other tests, or from the tested code. So what state should you
leave it in once you have finished? Perhaps you want all the output created by
your tested code to end up in the buffer as if it had been run normally (i.e.
not from within utPLSQL), or maybe you want only the text that was in the
buffer before you started to be left.
</p>
<p>
This package attempts to allow to do any of these. There is a flag in the
package to determine whether text pulled from the output buffer should be
saved. This is set with 'save' and 'nosave' and returned by
'saving'. Data is pulled from the buffer using 'extract',
while the procedure 'replace' puts any saved data back into the output
buffer.
</p>
<p>The intent is that it is used like this:</p>
<pre>
PROCEDURE ut_my_test IS
BEGIN
--Pull out any text already in the output buffer
utoutput.save;
utoutput.extract;
--Your testing code here, with saving turned on or off as you see fit
--Put text back in the output buffer
utoutput.replace;
END;
</pre>
<p>
So to start with, we save any text already in the buffer. We then carry out
our testing. If we want the output generated by the testing to end up back in
the output buffer, we turn on saving. Finally, we put the saved text back.
</p>
<h3>Warning</h3>
<p>
In the current version of utPLSQL (2.0.9.1) use of this package is virtually impossible with
<a href="utplsql.html#Trace">utPLSQL tracing</a> turned on. The reason for this is that this facility writes output using
DBMS_OUTPUT every time an assertion is called.
</p>
<h2><a name="Saving">Saving Output</a></h2>
<p>The three routines for handling the save flag are:</p>
<pre>
PROCEDURE save;
PROCEDURE nosave;
FUNCTION saving RETURN BOOLEAN;
</pre>
<p>
Quite simply, 'save' turns the flag on, 'nosave' turns it off and 'saving'
returns its current value.
</p>
<h2><a name="Extract">Extracting Output</a></h2>
<p>There are 4 versions of the extract routine to get text from the output buffer:</p>
<pre>
FUNCTION extract (
buffer_out OUT DBMS_OUTPUT.CHARARR,
max_lines_in IN INTEGER := NULL,
save_in IN BOOLEAN := saving
) RETURN INTEGER;
PROCEDURE extract (
buffer_out OUT DBMS_OUTPUT.CHARARR,
max_lines_in IN INTEGER := NULL,
save_in IN BOOLEAN := saving
);
FUNCTION extract(
max_lines_in IN INTEGER := NULL,
save_in IN BOOLEAN := saving
) RETURN INTEGER;
PROCEDURE extract(
max_lines_in IN INTEGER := NULL,
save_in IN BOOLEAN := saving
);
</pre>
<p>
The function versions return the number of lines extracted from the
DBMS_OUTPUT buffer. The other parameters are used as follows:
</p>
<ul>
<li>buffer_out - This is a buffer in which to put the extracted text.</li>
<li>max_lines_in - This is the maximum number of lines to be extracted. If NULL is passed in (the default) then all the lines are extracted.</li>
<li>save_in - This specifies if the extracted output should be saved. It overrides the global save flag.</li>
</ul>
<h2><a name = "Replace">Replacing Output</a></h2>
<p>The replace procedure takes no parameters:</p>
<pre>
PROCEDURE replace;
</pre>
<p>
It simply puts the saved text back into the DBMS_OUTPUT buffer. Note that
the buffer is emptied at this point.
</p>
<h2><a name = "NextLine">Checking Output Line-by-Line</a></h2>
<p>
The nextLine function makes it easy to check output line-by-line as it
simply extracts and returns the next line of output:
</p>
<pre>
FUNCTION nextLine(
raise_exc_in BOOLEAN := TRUE,
save_in BOOLEAN := saving
) RETURN VARCHAR2;
</pre>
<p>
The raise_exc_in flag determines if the function should throw the
exception utOutput.EMPTY_OUTPUT_BUFFER when asked for the next line from
an empty buffer. If no exception is thrown, NULL is returned. As with
extract, the save_in flag simply overrides the global save flag setting.
</p>
<h2><a name = "Count">Size of Output</a></h2>
<p>This function simply counts the number of lines present in the output buffer:</p>
<pre>
FUNCTION count RETURN INTEGER;
</pre>
<p>Note that the output itself is left untouched.</p>
<!-- End utPLSQL Body -->
<p><a href="utgen.html">< Previous Section: utGen Package</a> | <a href="utreceq.html">Next Section: utRecEq Package ></a></p>
<div class="purple_bar"><a href="index.html"><img src="utplsql.jpg" alt="utPLSQL logo" /></a></div>
<p>
<a href="http://validator.w3.org/check?uri=referer">
<img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0 Strict" height="31" width="88" />
</a>
</p>
<p class="copyright">Copyright © 2000-2005, 2014-2016 <a href="mailto:steven@stevenfeuerstein.com">Steven Feuerstein</a>, <a href="mailto:c@24.org.uk">Chris Rimmer</a>, <a href="mailto:pbarel@vda.nl">Patrick Barel</a> and the utPLSQL Project. All rights reserved</p>
</body>
</html>