Skip to content

Commit 53bdb32

Browse files
rloverlove
committed
Automated Doc Refresh from utPLSQL repo
1 parent 6874bba commit 53bdb32

30 files changed

+9394
-0
lines changed

‎docs/admin.html‎

Lines changed: 254 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
1+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2+
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3+
4+
5+
<!-- WARNING! This file is generated. -->
6+
<!-- To alter documentation, edit files in src directory -->
7+
8+
9+
<html xmlns="http://www.w3.org/1999/xhtml">
10+
<head>
11+
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
12+
<title>Administrative Topics</title>
13+
<link rel="stylesheet" href="utplsql.css" type="text/css" />
14+
<meta name="keywords" content="utPLSQL, PL\SQL, Unit Testing, Framework, Oracle" />
15+
<meta name="description" content="Unit Testing PL\SQL" />
16+
<meta name="title" content="Administrative Topics" />
17+
<meta name="author" content="Steven Feuerstein, Chris Rimmer, Patrick Barel and the utPLSQL Project" />
18+
<meta name="copyright" content="(C) 2000-2005, 2014-2016 Steven Feuerstein, Chris Rimmer, Patrick Barel and the utPLSQL Project" />
19+
</head>
20+
<body>
21+
<div class="purple_bar"><a href="index.html"><img src="utplsql.jpg" alt="utPLSQL logo" /></a></div>
22+
<p>[ <a href="index.html">Home</a>
23+
| <a href="started.html">Getting Started</a>
24+
| <a href="buildpack.html">Build Test Packages</a>
25+
| <a href="examples.html">Examples</a>
26+
| <a href="userguide.html">User Guide</a>
27+
| <a href="release.html">Release Notes</a>
28+
| <a href="map.html">Document Map</a> ]</p>
29+
<p><a href="fourstep.html">&lt; Previous Section: The Four Step Program to using utPLSQL</a> | <a href="buildpack.html">Next Section: Build Test Packages &gt;</a></p>
30+
<!-- Begin utPLSQL Body -->
31+
<!-- $Id$ -->
32+
<h1>Administrative Topics</h1>
33+
34+
<h3><a href="admin.html">Configuring UTL_FILE</a></h3>
35+
36+
<h3><a href="#Project_Team">Join the Project Team</a></h3>
37+
38+
<h3><a href="#Reporting">Reporting Bugs and Enhancement Requests</a></h3>
39+
40+
<h2><a name="Admin"></a>Administrative Topics</h2>
41+
42+
<h3><a name="UTL_FILE"></a>Configuring UTL_FILE</h3>
43+
<p>
44+
If you want utPLSQL to automatically recompile your test packages, you
45+
will need to make sure that UTL_FILE is enabled in your database (this
46+
allows you to read/write operating system files). The database initialization
47+
parameter file (aka, the "init.ora" file) must have at least one utl_file_dir
48+
parameter in it for this to work. Here is some background and guidelines
49+
for working with UTL_FILE:
50+
</p>
51+
<p>
52+
UTL_FILE lets you read and write files accessible from the server on
53+
which your database is running. So, theoretically, you could use UTL_FILE
54+
to write right over your tablespace data files, control files and so on.
55+
That is, of course, a very bad idea. Server security requires the ability
56+
to place restrictions on where you can read and write your files.
57+
</p>
58+
<p>
59+
UTL_FILE implements this security by limiting access to files that reside
60+
in one of the directories specified in the init.ora file (parameter initialization
61+
file) for the database instance on which UTL_FILE is running.
62+
</p>
63+
<p>
64+
When you call UTL_FILE.FOPEN to open a file, you must specify both the
65+
location and the name of the file, in separate arguments. This file location
66+
is then checked against the list of accessible directories.
67+
</p>
68+
<p>
69+
The format of the parameter for file access in the init.ora file is:
70+
</p>
71+
<pre>
72+
utl_file_dir = &lt;directory&gt;
73+
</pre>
74+
<p>
75+
Include a parameter for utl_file_dir for each directory you want to make
76+
accessible for UTL_FILE operations. The following entries, for example,
77+
enable four different directories in Unix:
78+
</p>
79+
80+
<pre>
81+
utl_file_dir = /tmp
82+
utl_file_dir = /ora_apps/hr/time_reporting
83+
utl_file_dir = /ora_apps/hr/time_reporting/log
84+
utl_file_dir = /users/test_area
85+
</pre>
86+
87+
<p>
88+
To bypass server security and allow read/write access to all directories,
89+
you can use this special syntax:
90+
</p>
91+
92+
<pre>
93+
utl_file_dir = *
94+
</pre>
95+
96+
<p>
97+
You should not use this option on production systems. In a development
98+
system, this entry certainly makes it easier for developers to get up and
99+
running on UTL_FILE and test their code. You should, however, only allow
100+
access to a few specific directories when you move the application to production.
101+
</p>
102+
<h4>Some observations on working with and setting up accessible directories with UTL_FILE:</h4>
103+
<p>
104+
Access is not recursive through subdirectories. If the following lines
105+
were in your init.ora file, for example,
106+
</p>
107+
108+
<pre>
109+
utl_file_dir = c:\group\dev1
110+
utl_file_dir = c:\group\prod\oe
111+
utl_file_dir = c:\group\prod\ar
112+
</pre>
113+
114+
<p>
115+
then you would not be able to open a file in the c:\group\prod\oe\reports
116+
subdirectory.
117+
</p>
118+
<p>
119+
Do not include the following entry in Unix systems:
120+
</p>
121+
122+
<pre>
123+
utl_file_dir = .
124+
</pre>
125+
126+
<p>
127+
This would allow you to read/write on the current directory in the operating
128+
system.
129+
</p>
130+
<p>
131+
Do not enclose the directory names within single or double quotes.
132+
</p>
133+
<p>
134+
In the UNIX environment, a file created by UTL_FILE.FOPEN has as its
135+
owner the shadow process running the Oracle instance. This is usually the
136+
oracle owner. If you try to access these files outside of UTL_FILE, you
137+
will need to have the correct privileges (or be logged in as oracle) to
138+
access or change these files.
139+
</p>
140+
<p>
141+
You should not end your directory name with a delimiter, such as the
142+
forward slash in Unix. The following specification of a directory will
143+
result in problems when trying to read from or write to the directory:
144+
</p>
145+
146+
<pre>
147+
utl_file_dir = /tmp/orafiles/
148+
</pre>
149+
150+
<p>
151+
After you modify your parameter initialization file, you will need to stop
152+
and then restart your database instance.
153+
</p>
154+
<h4>Test UTL_FILE Access</h4>
155+
<p>
156+
If you have never before used or relied on UTL_FILE, you should write
157+
a simple test to verify that UTL_FILE is now working. You can use the code
158+
shown below (after changing your directory names and names for existing
159+
and new files) to make sure you've got it running properly.
160+
</p>
161+
162+
<pre>
163+
SET SERVEROUTPUT ON
164+
165+
DECLARE
166+
fid UTL_FILE.FILE_TYPE;
167+
v VARCHAR2(32767);
168+
PROCEDURE recNgo (str IN VARCHAR2)
169+
IS
170+
BEGIN
171+
DBMS_OUTPUT.PUT_LINE ('UTL_FILE error ' || str);
172+
173+
UTL_FILE.FCLOSE (fid);
174+
END;
175+
BEGIN
176+
/* Change the directory name to one to which you at least
177+
|| THINK you have read/write access.
178+
*/
179+
fid := UTL_FILE.FOPEN ('e:\demo', 'existing_file', 'R');
180+
UTL_FILE.GET_LINE (fid, v);
181+
dbms_output.put_line (v);
182+
183+
UTL_FILE.FCLOSE (fid);
184+
185+
fid := UTL_FILE.FOPEN ('e:\demo', 'new_file', 'W');
186+
187+
UTL_FILE.PUT_LINE (fid, v);
188+
189+
UTL_FILE.FCLOSE (fid);
190+
EXCEPTION
191+
WHEN UTL_FILE.INVALID_PATH
192+
THEN recNgo ('invalid_path');
193+
WHEN UTL_FILE.INVALID_MODE
194+
THEN recNgo ('invalid_mode');
195+
WHEN UTL_FILE.INVALID_FILEHANDLE
196+
THEN recNgo ('invalid_filehandle');
197+
WHEN UTL_FILE.INVALID_OPERATION
198+
THEN recNgo ('invalid_operation');
199+
WHEN UTL_FILE.READ_ERROR
200+
THEN recNgo ('read_error');
201+
WHEN UTL_FILE.WRITE_ERROR
202+
THEN recNgo ('write_error');
203+
WHEN UTL_FILE.INTERNAL_ERROR
204+
THEN recNgo ('internal_error');
205+
END;
206+
/
207+
</pre>
208+
<p>
209+
If an error occurs, it will be displayed on your screen (note: the "set
210+
serveroutput on" is not required for UTL_FILE to work, but simply to display
211+
any errors which might occur).
212+
</p>
213+
214+
<h3><a name="Project_Team"></a>Join the utPLSQL Project Team</h3>
215+
216+
<p>
217+
To take part in the utPLSQL project, have a look round the
218+
<a href = "https://github.com/utPLSQL/utPLSQL">utPLSQL project site</a>,
219+
in particular the <a href = "https://github.com/utPLSQL/utPLSQL/blob/master/CONTRIBUTING.md">CONTRIBUTING.md</a>
220+
and <a href = "https://github.com/utPLSQL/utPLSQL/issues">issues tracker</a>.
221+
Once you are up to speed on the project, you can choose a issue and begin to contribute.
222+
</p>
223+
224+
<h3><a name="Reporting"></a>Reporting Bugs and Enhancement Requests</h3>
225+
226+
<p>
227+
To identify the version of utPLSQL you are running,
228+
you can execute the following program in SQL*Plus:
229+
</p>
230+
231+
<pre>
232+
SQL&gt; set serveroutput on
233+
SQL&gt; exec dbms_output.put_line (utPLSQL.version)
234+
</pre>
235+
236+
<p>
237+
You can also look inside the utPLSQL package (utPLSQL.pkb)
238+
and check the value of the g_version private variable.
239+
</p>
240+
241+
<!-- End utPLSQL Body -->
242+
<p><a href="fourstep.html">&lt; Previous Section: The Four Step Program to using utPLSQL</a> | <a href="buildpack.html">Next Section: Build Test Packages &gt;</a></p>
243+
244+
<div class="purple_bar"><a href="index.html"><img src="utplsql.jpg" alt="utPLSQL logo" /></a></div>
245+
246+
<p>
247+
<a href="http://validator.w3.org/check?uri=referer">
248+
<img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0 Strict" height="31" width="88" />
249+
</a>
250+
</p>
251+
252+
<p class="copyright">Copyright &copy; 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>
253+
</body>
254+
</html>

‎docs/buildpack.html‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2+
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3+
4+
5+
<!-- WARNING! This file is generated. -->
6+
<!-- To alter documentation, edit files in src directory -->
7+
8+
9+
<html xmlns="http://www.w3.org/1999/xhtml">
10+
<head>
11+
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
12+
<title>Build Test Packages</title>
13+
<link rel="stylesheet" href="utplsql.css" type="text/css" />
14+
<meta name="keywords" content="utPLSQL, PL\SQL, Unit Testing, Framework, Oracle" />
15+
<meta name="description" content="Unit Testing PL\SQL" />
16+
<meta name="title" content="Build Test Packages" />
17+
<meta name="author" content="Steven Feuerstein, Chris Rimmer, Patrick Barel and the utPLSQL Project" />
18+
<meta name="copyright" content="(C) 2000-2005, 2014-2016 Steven Feuerstein, Chris Rimmer, Patrick Barel and the utPLSQL Project" />
19+
</head>
20+
<body>
21+
<div class="purple_bar"><a href="index.html"><img src="utplsql.jpg" alt="utPLSQL logo" /></a></div>
22+
<p>[ <a href="index.html">Home</a>
23+
| <a href="started.html">Getting Started</a>
24+
| <a href="buildpack.html">Build Test Packages</a>
25+
| <a href="examples.html">Examples</a>
26+
| <a href="userguide.html">User Guide</a>
27+
| <a href="release.html">Release Notes</a>
28+
| <a href="map.html">Document Map</a> ]</p>
29+
<p><a href="admin.html">&lt; Previous Section: Administrative Topics</a> | <a href="howto.html">Next Section: How to build a test package &gt;</a></p>
30+
<!-- Begin utPLSQL Body -->
31+
<!-- $Id$ -->
32+
<h1>Build Test Packages</h1>
33+
34+
<p>
35+
We learn best by following the examples of those who have gone before
36+
us. So you will find in this document sample test packages and different
37+
approaches to using utPLSQL to test your PL/SQL code like it has never
38+
been tested before!
39+
</p>
40+
<p>
41+
Spend some time in the general <a href="howto.html">How to Build a Test
42+
Package</a> so that you are comfortable with the basic steps necessary
43+
to integrate your test code into the utPLSQL framework. The Test Run section
44+
offers a narrative presentation of building a test package; it makes a
45+
nice follow-up to the How To section if you still feel any uncertainty.
46+
Then you will be more than ready to explore the <a href="examples.html">Examples</a>.
47+
</p>
48+
49+
<h2><a href="howto.html">How to Build a Test Package</a></h2>
50+
51+
<h2><a href="testrun.html">A "Test Run" with utPLSQL</a></h2>
52+
53+
<!-- End utPLSQL Body -->
54+
<p><a href="admin.html">&lt; Previous Section: Administrative Topics</a> | <a href="howto.html">Next Section: How to build a test package &gt;</a></p>
55+
56+
<div class="purple_bar"><a href="index.html"><img src="utplsql.jpg" alt="utPLSQL logo" /></a></div>
57+
58+
<p>
59+
<a href="http://validator.w3.org/check?uri=referer">
60+
<img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0 Strict" height="31" width="88" />
61+
</a>
62+
</p>
63+
64+
<p class="copyright">Copyright &copy; 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>
65+
</body>
66+
</html>

0 commit comments

Comments
 (0)