1 PACKAGE utl_file AUTHID CURRENT_USER AS
2
3 /*
4 ** FILE_TYPE - File handle
5 */
6
7 TYPE file_type IS RECORD (id BINARY_INTEGER,
8 datatype BINARY_INTEGER,
9 byte_mode BOOLEAN);
10
11 /*
12 ** Exceptions
13 */
14 file_open EXCEPTION;
15 charsetmismatch EXCEPTION;
16 invalid_path EXCEPTION;
17 invalid_mode EXCEPTION;
18 invalid_filehandle EXCEPTION;
19 invalid_operation EXCEPTION;
20 read_error EXCEPTION;
21 write_error EXCEPTION;
22 internal_error EXCEPTION;
23 invalid_maxlinesize EXCEPTION;
24 invalid_filename EXCEPTION;
25 access_denied EXCEPTION;
26 invalid_offset EXCEPTION;
27 delete_failed EXCEPTION;
28 rename_failed EXCEPTION;
29
30 charsetmismatch_errcode CONSTANT PLS_INTEGER:= -29298;
31 invalid_path_errcode CONSTANT PLS_INTEGER:= -29280;
32 invalid_mode_errcode CONSTANT PLS_INTEGER:= -29281;
33 invalid_filehandle_errcode CONSTANT PLS_INTEGER:= -29282;
34 invalid_operation_errcode CONSTANT PLS_INTEGER:= -29283;
35 read_error_errcode CONSTANT PLS_INTEGER:= -29284;
36 write_error_errcode CONSTANT PLS_INTEGER:= -29285;
37 internal_error_errcode CONSTANT PLS_INTEGER:= -29286;
38 invalid_maxlinesize_errcode CONSTANT PLS_INTEGER:= -29287;
39 invalid_filename_errcode CONSTANT PLS_INTEGER:= -29288;
40 access_denied_errcode CONSTANT PLS_INTEGER:= -29289;
41 invalid_offset_errcode CONSTANT PLS_INTEGER:= -29290;
42 delete_failed_errcode CONSTANT PLS_INTEGER:= -29291;
43 rename_failed_errcode CONSTANT PLS_INTEGER:= -29292;
44
45 PRAGMA EXCEPTION_INIT(charsetmismatch, -29298);
46 PRAGMA EXCEPTION_INIT(invalid_path, -29280);
47 PRAGMA EXCEPTION_INIT(invalid_mode, -29281);
48 PRAGMA EXCEPTION_INIT(invalid_filehandle, -29282);
49 PRAGMA EXCEPTION_INIT(invalid_operation, -29283);
50 PRAGMA EXCEPTION_INIT(read_error, -29284);
51 PRAGMA EXCEPTION_INIT(write_error, -29285);
52 PRAGMA EXCEPTION_INIT(internal_error, -29286);
53 PRAGMA EXCEPTION_INIT(invalid_maxlinesize, -29287);
54 PRAGMA EXCEPTION_INIT(invalid_filename, -29288);
55 PRAGMA EXCEPTION_INIT(access_denied, -29289);
56 PRAGMA EXCEPTION_INIT(invalid_offset, -29290);
57 PRAGMA EXCEPTION_INIT(delete_failed, -29291);
58 PRAGMA EXCEPTION_INIT(rename_failed, -29292);
59
60 /*
61 ** FOPEN - open file
62 **
63 ** As of 8.0.6, you can have a maximum of 50 files open simultaneously.
64 **
65 ** As of 9.0.2, UTL_FILE allows file system access for directories
66 ** created as database objects. See the CREATE DIRECTORY command.
67 ** Directory object names are case sensitive and must match exactly
68 ** the NAME string in ALL_DIRECTORIES. The LOCATION parameter may be
69 ** either a directory string from the UTL_FILE_DIR init.ora parameter
70 ** or a directory object name.
71 **
72 ** IN
73 ** location - directory location of file
74 ** filename - file name (including extention)
75 ** open_mode - open mode ('r', 'w', 'a' 'rb', 'wb', 'ab')
76 ** max_linesize - maximum number of characters per line, including the
77 ** newline character, for this file.
78 ** Valid values are 1 through 32767 and NULL. A NULL
79 ** value for max_linesize indicates that UTL_FILE should
80 ** calculate an operating system specific value at runtime.
81 ** RETURN
82 ** file_type handle to open file
83 ** EXCEPTIONS
84 ** invalid_path - file location or name was invalid
85 ** invalid_mode - the open_mode string was invalid
86 ** invalid_operation - file could not be opened as requested
87 ** invalid_maxlinesize - specified max_linesize is too large or too small
88 ** access_denied - access to the directory object is denied
89 */
90 FUNCTION fopen(location IN VARCHAR2,
91 filename IN VARCHAR2,
92 open_mode IN VARCHAR2,
93 max_linesize IN BINARY_INTEGER DEFAULT NULL)
94 RETURN file_type;
95 PRAGMA RESTRICT_REFERENCES(fopen, WNDS, RNDS, TRUST);
96
97 /*
98 ** FOPEN_NCHAR - open file
99 **
100 ** Note: since NCHAR contains mutibyte character, it is highly recommended
101 ** that the max_linesize is less than 6400.
102 */
103
104 FUNCTION fopen_nchar(location IN VARCHAR2,
105 filename IN VARCHAR2,
106 open_mode IN VARCHAR2,
107 max_linesize IN BINARY_INTEGER DEFAULT NULL)
108 RETURN file_type;
109 PRAGMA RESTRICT_REFERENCES(fopen_nchar, WNDS, RNDS, TRUST);
110
111 /*
112 ** IS_OPEN - Test if file handle is open
113 **
114 ** IN
115 ** file - File handle
116 **
117 ** RETURN
118 ** BOOLEAN - Is file handle open/valid?
119 */
120 FUNCTION is_open(file IN file_type) RETURN BOOLEAN;
121 PRAGMA RESTRICT_REFERENCES(is_open, WNDS, RNDS, WNPS, RNPS, TRUST);
122
123 /*
124 ** FCLOSE - close an open file
125 **
126 ** IN
127 ** file - File handle (open)
128 ** EXCEPTIONS
129 ** invalid_filehandle - not a valid file handle
130 ** write_error - OS error occured during write operation
131 */
132 PROCEDURE fclose(file IN OUT file_type);
133 PRAGMA RESTRICT_REFERENCES(fclose, WNDS, RNDS, TRUST);
134
135 /*
136 ** FCLOSE_ALL - close all open files for this session
137 **
138 ** For Emergency/Cleanup use only. FILE_TYPE handles will not be
139 ** cleared (IS_OPEN will still indicate they are valid)
140 **
141 ** IN
142 ** file - File handle (open)
143 ** EXCEPTIONS
144 ** write_error - OS error occured during write operation
145 */
146 PROCEDURE fclose_all;
147 PRAGMA RESTRICT_REFERENCES(fclose_all, WNDS, RNDS, TRUST);
148 /*
149 ** GET_LINE - Get (read) a line of text from the file
150 **
151 ** IN
152 ** file - File handle (open in read mode)
153 ** len - input buffer length, default is null, max is 32767
154 ** OUT
155 ** buffer - next line of text in file
156 ** EXCEPTIONS
157 ** no_data_found - reached the end of file
158 ** value_error - line to long to store in buffer
159 ** invalid_filehandle - not a valid file handle
160 ** invalid_operation - file is not open for reading
161 ** - file is open for byte mode access
162 ** read_error - OS error occurred during read
163 ** charsetmismatch - if the file is open for nchar data.
164 */
165 PROCEDURE get_line(file IN file_type,
166 buffer OUT VARCHAR2,
167 len IN BINARY_INTEGER DEFAULT NULL);
168 PRAGMA RESTRICT_REFERENCES(get_line, WNDS, RNDS, WNPS, RNPS, TRUST);
169
170 /* GET_LINE_NCHAR - Get (read a line of nchar data from the file.
171 **
172 ** IN
173 ** file - File handle (open in read mode)
174 ** len - input buffer length, default is null, max is 32767
175 ** OUT
176 ** buffer - next line of text in file
177 ** the data might be convert from UTF8 to current charset.
178 ** EXCEPTIONS
179 ** no_data_found - reached the end of file
180 ** value_error - line to long to store in buffer
181 ** invalid_filehandle - not a valid file handle
182 ** invalid_operation - file is not open for reading
183 ** - file is open for byte mode access
184 ** read_error - OS error occurred during read
185 ** charsetmismatch - if the file is open for char data.
186 */
187 PROCEDURE get_line_nchar(file IN file_type,
188 buffer OUT NVARCHAR2,
189 len IN BINARY_INTEGER DEFAULT NULL);
190 PRAGMA RESTRICT_REFERENCES(get_line_nchar, WNDS, RNDS, WNPS, TRUST);
191
192 /*
193 ** PUT - Put (write) text to file
194 **
195 ** IN
196 ** file - File handle (open in write/append mode)
197 ** buffer - Text to write
198 ** EXCEPTIONS
199 ** invalid_filehandle - not a valid file handle
200 ** invalid_operation - file is not open for writing/appending
201 ** - file is open for byte mode access
202 ** write_error - OS error occured during write operation
203 ** charsetmismatch - if the file is open for nchar data.
204 */
205 PROCEDURE put(file IN file_type,
206 buffer IN VARCHAR2);
207 PRAGMA RESTRICT_REFERENCES(put, WNDS, RNDS, TRUST);
208
209 /*
210 ** PUT_NCHAR - Put (write) nchar data to file
211 ** IN
212 ** file - File handle (open in write/append mode)
213 ** buffer - Text to write. the data will convert to UTF8 if needed.
214 ** EXCEPTIONS
215 ** invalid_filehandle - not a valid file handle
216 ** invalid_operation - file is not open for writing/appending
217 ** - file is open for byte mode access
218 ** write_error - OS error occured during write operation
219 ** charsetmismatch - if the file is open for char data.
220 */
221 PROCEDURE put_nchar(file IN file_type,
222 buffer IN NVARCHAR2);
223 PRAGMA RESTRICT_REFERENCES(put_nchar, WNDS, RNDS, TRUST);
224
225 /*
226 ** NEW_LINE - Write line terminators to file
227 **
228 ** IN
229 ** file - File handle (open in write/append mode)
230 ** lines - Number of newlines to write (default 1)
231 ** EXCEPTIONS
232 ** invalid_filehandle - not a valid file handle
233 ** invalid_operation - file is not open for writing/appending
234 ** - file is open for byte mode access
235 ** write_error - OS error occured during write operation
236 */
237 PROCEDURE new_line(file IN file_type,
238 lines IN NATURAL := 1);
239 PRAGMA RESTRICT_REFERENCES(new_line, WNDS, RNDS, TRUST);
240
241 /*
242 ** PUT_LINE - Put (write) line to file
243 **
244 ** IN
245 ** file - File handle (open in write/append mode)
246 ** buffer - Text to write.
247 ** autoflush - Flush following write, default=no flush
248 ** EXCEPTIONS
249 ** invalid_filehandle - not a valid file handle
250 ** invalid_operation - file is not open for writing/appending
251 ** - file is open for byte mode access
252 ** write_error - OS error occured during write operation
253 ** charsetmismatch - if the file is open for nchar data.
254 */
255 PROCEDURE put_line(file IN file_type,
256 buffer IN VARCHAR2,
257 autoflush IN BOOLEAN DEFAULT FALSE);
258 PRAGMA RESTRICT_REFERENCES(put_line, WNDS, RNDS, TRUST);
259
260 /*
261 ** PUT_LINE_NCHAR - Put (write) line of nchar data to file
262 ** IN
263 ** file - File handle (open in write/append mode)
264 ** buffer - Text to write. The data might convert to UTF8 if needed.
265 ** EXCEPTIONS
266 ** invalid_filehandle - not a valid file handle
267 ** invalid_operation - file is not open for writing/appending
268 ** - file is open for byte mode access
269 ** write_error - OS error occured during write operation
270 ** charsetmismatch - if the file is open for char data.
271 */
272 PROCEDURE put_line_nchar(file IN file_type,
273 buffer IN NVARCHAR2);
274 PRAGMA RESTRICT_REFERENCES(put_line_nchar, WNDS, RNDS, TRUST);
275
276 /*
277 ** PUTF - Put (write) formatted text to file
278 **
279 ** Format string special characters
280 ** '%s' - substitute with next argument
281 ** '\n' - newline (line terminator)
282 **
283 ** IN
284 ** file - File handle (open in write/append mode)
285 ** format - Formatting string
286 ** arg1 - Substitution argument #1
287 ** ...
288 ** EXCEPTIONS
289 ** invalid_filehandle - not a valid file handle
290 ** invalid_operation - file is not open for writing/appending
291 ** - file is open for byte mode access
292 ** write_error - OS error occured during write operation
293 ** charsetmismatch - if the file is open for nchar data.
294 */
295 procedure putf(file IN file_type,
296 format IN VARCHAR2,
297 arg1 IN VARCHAR2 DEFAULT NULL,
298 arg2 IN VARCHAR2 DEFAULT NULL,
299 arg3 IN VARCHAR2 DEFAULT NULL,
300 arg4 IN VARCHAR2 DEFAULT NULL,
301 arg5 IN VARCHAR2 DEFAULT NULL);
302 PRAGMA RESTRICT_REFERENCES(putf, WNDS, RNDS, TRUST);
303
304 /*
305 ** PUTF_NCHAR - Put (write) formatted text to file
306 **
307 ** Format string special characters
308 ** N'%s' - substitute with next argument
309 ** N'\n' - newline (line terminator)
310 **
311 ** IN
312 ** file - File handle (open in write/append mode)
313 ** format - Formatting string
314 ** arg1 - Substitution argument #1
315 ** ...
316 ** EXCEPTIONS
317 ** invalid_filehandle - not a valid file handle
318 ** invalid_operation - file is not open for writing/appending
319 ** - file is open for byte mode access
320 ** write_error - OS error occured during write operation
321 ** charsetmismatch - if the file is open for char data.
322
323 */
324 procedure putf_nchar(file IN file_type,
325 format IN NVARCHAR2,
326 arg1 IN NVARCHAR2 DEFAULT NULL,
327 arg2 IN NVARCHAR2 DEFAULT NULL,
328 arg3 IN NVARCHAR2 DEFAULT NULL,
329 arg4 IN NVARCHAR2 DEFAULT NULL,
330 arg5 IN NVARCHAR2 DEFAULT NULL);
331 PRAGMA RESTRICT_REFERENCES(putf_nchar, WNDS, RNDS, TRUST);
332
333 /*
334 ** FFLUSH - Force physical write of buffered output
335 **
336 ** IN
337 ** file - File handle (open in write/append mode)
338 ** EXCEPTIONS
339 ** invalid_filehandle - not a valid file handle
340 ** invalid_operation - file is not open for writing/appending
341 ** write_error - OS error occured during write operation
342 */
343 PROCEDURE fflush(file IN file_type);
344 PRAGMA RESTRICT_REFERENCES(fflush, WNDS, RNDS, TRUST);
345
346 /*
347 ** PUT_RAW - Write a raw value to file.
348 **
349 ** IN file - File handle (open in write/append mode)
350 ** IN buffer - Raw data
351 ** IN autoflush - Flush following write, default=no flush
352 ** EXCEPTIONS
353 ** invalid_filehandle - not a valid file handle
354 ** invalid_operation - file is not open for writing/appending
355 ** write_error - OS error occured during write operation
356 */
357 PROCEDURE put_raw(file IN file_type,
358 buffer IN RAW,
359 autoflush IN BOOLEAN DEFAULT FALSE);
360 PRAGMA RESTRICT_REFERENCES(put_raw, WNDS, RNDS, TRUST);
361
362 /*
363 ** GET_RAW - Read a raw value from file.
364 **
365 ** The GET_RAW() will read until it sees a line termination character
366 ** or until the number of bytes specified in the LEN parameter has been read.
367 **
368 ** IN file - File handle (open in write/append mode)
369 ** OUT buffer - Raw data
370 ** IN len - Nubmer of bytes to be read
371 ** EXCEPTIONS
372 ** invalid_filehandle - not a valid file handle
373 ** invalid_operation - file is not open for writing/appending
374 ** read_error - OS error occured during read operation
375 */
376 PROCEDURE get_raw(file IN file_type,
377 buffer OUT NOCOPY RAW,
378 len IN BINARY_INTEGER DEFAULT NULL);
379 PRAGMA RESTRICT_REFERENCES(get_raw, WNDS, RNDS, TRUST);
380
381 /*
382 ** FSEEK - Move the file pointer to a specified position within the file.
383 **
384 ** IN file - File handle (open in write/append mode)
385 ** IN absolute_offset - Absolute offset to which to seek.
386 ** IN relative_offset - Relative offset, forward or backwards, to which
387 ** to seek.
388 **
389 ** The file must be open in read mode in order to use fseek().
390 **
391 ** If both absolute_offset and relative_offset are not NULL, absolute_offset
392 ** takes precedence. A negative relative_offset will cause fseek to
393 ** close and reopen the file and seek in a forward direction.
394 **
395 ** EXCEPTIONS
396 ** invalid_filehandle - not a valid file handle
397 ** invalid_offset - file is not open for writing/appending
398 ** invalid_operation - file is opened for byte mode access
399 */
400 PROCEDURE fseek(file IN OUT file_type,
401 absolute_offset IN BINARY_INTEGER DEFAULT NULL,
402 relative_offset IN BINARY_INTEGER DEFAULT NULL);
403 PRAGMA RESTRICT_REFERENCES(fseek, WNDS, RNDS, TRUST);
404
405 /*
406 ** FREMOVE - Delete the specified file from disk.
407 **
408 ** IN location - directory location of file
409 ** IN filename - file name (including extention)
410 ** EXCEPTIONS
411 ** invalid_path - not a valid file handle
412 ** invalid_filename - file not found or file name NULL
413 ** file_open - file is not open for writing/appending
414 ** access_denied - access to the directory object is denied
415 ** remove_failed - failed to delete file
416 */
417 PROCEDURE fremove(location IN VARCHAR2,
418 filename IN VARCHAR2);
419 PRAGMA RESTRICT_REFERENCES(fremove, WNDS, RNDS, TRUST);
420
421 /*
422 ** FCOPY - Copy all or part of a file to a new file.
423 **
424 ** IN location - source directory of file
425 ** IN filename - source file name (including extention)
426 ** IN dest_dir - destination directory of file
427 ** IN dest_file - destination file name (including extention)
428 ** IN start_line - line number from which to begin copying, default is
429 ** 1 referring to the first line in the file
430 ** IN end_line - line number from which to end copying, default is NULL
431 ** referring to end-of-file
432 ** EXCEPTIONS
433 ** invalid_path - not a valid file handle
434 ** invalid_filename - file not found or file name is NULL
435 ** invalid_lineno - bad start_line or end_line value
436 */
437 PROCEDURE fcopy(src_location IN VARCHAR2,
438 src_filename IN VARCHAR2,
439 dest_location IN VARCHAR2,
440 dest_filename IN VARCHAR2,
441 start_line IN BINARY_INTEGER DEFAULT 1,
442 end_line IN BINARY_INTEGER DEFAULT NULL);
443 PRAGMA RESTRICT_REFERENCES(fcopy, WNDS, RNDS, TRUST);
444
445 /*
446 ** FGETATTR - Get file attributes
447 **
448 ** IN location - directory location of file
449 ** IN filename - file name (including extention)
450 ** OUT fexists - true or false, for exists or doesn't exist. Note:
451 ** the following parameters have no meaning if the file
452 ** doesn't exist, in which case, they return NULL.
453 ** OUT file_length - length of the file in bytes.
454 ** OUT block_size - filesystem block size in bytes.
455 ** EXCEPTIONS
456 ** invalid_path - not a valid file handle
457 ** invalid_filename - file not found or file name NULL
458 ** file_open - file is not open for writing/appending
459 ** access_denied - access to the directory object is denied
460 */
461 PROCEDURE fgetattr(location IN VARCHAR2,
462 filename IN VARCHAR2,
463 fexists OUT BOOLEAN,
464 file_length OUT NUMBER,
465 block_size OUT BINARY_INTEGER);
466 PRAGMA RESTRICT_REFERENCES(fgetattr, WNDS, RNDS, TRUST);
467
468 /*
469 ** FGETPOS - Return the current position in the file in bytes.
470 **
471 ** IN file - File handle (open in write/append mode)
472 ** EXCEPTIONS
473 ** invalid_filehandle - not a valid file handle
474 ** invalid_operation - file is not open for writing/appending
475 ** invalid_operation - file is open for byte mode access
476 */
477 FUNCTION fgetpos(file IN file_type) RETURN BINARY_INTEGER;
478 PRAGMA RESTRICT_REFERENCES(fgetpos, WNDS, RNDS, TRUST);
479
480 /*
481 ** FRENAME - Rename a file to a new name.
482 **
483 ** IN location - source directory of file
484 ** IN filename - source file name (including extention)
485 ** IN dest_dir - destination directory of file
486 ** IN dest_file - destination file name (including extention)
487 ** IN overwrite - boolean signifying whether to overwrite an existing
488 ** in the event that one exists, default no overwrite
489 ** EXCEPTIONS
490 ** invalid_path - not a valid file handle
491 ** invalid_filename - file not found or file name NULL
492 ** rename_failed - rename of the file failed
493 ** access_denied - access to the directory object is denied
494 */
495 PROCEDURE frename(src_location IN VARCHAR2,
496 src_filename IN VARCHAR2,
497 dest_location IN VARCHAR2,
498 dest_filename IN VARCHAR2,
499 overwrite IN BOOLEAN DEFAULT FALSE);
500 PRAGMA RESTRICT_REFERENCES(frename, WNDS, RNDS, TRUST);
501
502 END utl_file;
[Home] [Help]