Release 2 (9.2)
Part Number A96612-01
 Home |
 Book List |
 Contents |
 Index |
 Master Index |
 Feedback |
| Oracle9i Supplied PL/SQL Packages and Types Reference Release 2 (9.2) Part Number A96612-01 |
|
UTL_FILE , 2 of 2
This function opens a file. You can specify the maximum line size and have a maximum of 50 files open simultaneously. See also "FOPEN_NCHAR Function".
UTL_FILE.FOPEN ( location IN VARCHAR2, filename IN VARCHAR2, open_mode IN VARCHAR2, max_linesize IN BINARY_INTEGER) RETURN file_type;
FOPEN returns a file handle, which must be passed to all subsequent procedures that operate on that file. The specific contents of the file handle are private to the UTL_FILE package, and individual components should not be referenced or changed by the UTL_FILE user.
| Return | Description |
|---|---|
|
file_type |
Handle to open file. |
INVALID_PATH: File location or name was invalid.INVALID_MODE: Theopen_modestring was invalid.INVALID_OPERATION: File could not be opened as requested.INVALID_MAXLINESIZE: Specifiedmax_linesizeis too large or too small.
This function opens a file in Unicode for input or output, with the maximum line size specified. You can have a maximum of 50 files open simultaneously. With this function, you can read or write a text file in Unicode instead of in the database charset. See also FOPEN Function.
UTL_FILE.FOPEN_NCHAR ( location IN VARCHAR2, filename IN VARCHAR2, open_mode IN VARCHAR2, max_linesize IN BINARY_INTEGER) RETURN file_type;
This function tests a file handle to see if it identifies an open file. IS_OPEN reports only whether a file handle represents a file that has been opened, but not yet closed. It does not guarantee that there will be no operating system errors when you attempt to use the file handle.
UTL_FILE.IS_OPEN ( file IN FILE_TYPE) RETURN BOOLEAN;
| Parameter | Description |
|---|---|
|
file |
Active file handle returned by an |
TRUE or FALSE
None.
This procedure closes an open file identified by a file handle. If there is buffered data yet to be written when FCLOSE runs, then you may receive a WRITE_ERROR exception when closing a file.
UTL_FILE.FCLOSE ( file IN OUT FILE_TYPE);
| Parameter | Description |
|---|---|
|
file |
Active file handle returned by an |
WRITE_ERRORINVALID_FILEHANDLE
This procedure closes all open file handles for the session. This should be used as an emergency cleanup procedure, for example, when a PL/SQL program exits on an exception.
UTL_FILE.FCLOSE_ALL;
None.
WRITE_ERROR
This procedure reads text from the open file identified by the file handle and places the text in the output buffer parameter. Text is read up to, but not including, the line terminator, or up to the end of the file, or up to the end of the linesize parameter. It cannot exceed the max_linesize specified in FOPEN.
If the line does not fit in the buffer, then a VALUE_ERROR exception is raised. If no text was read due to end of file, then the NO_DATA_FOUND exception is raised.
Because the line terminator character is not read into the buffer, reading blank lines returns empty strings.
The maximum size of the buffer parameter is 32767 bytes unless you specify a smaller size in FOPEN. The default is approximately 1000 bytes, depending on your platform. See also "GET_LINE_NCHAR Procedure".
UTL_FILE.GET_LINE ( file IN FILE_TYPE, buffer OUT VARCHAR2, linesize IN NUMBER, len IN PLS_INTEGER DEFAULT NULL);
INVALID_FILEHANDLEINVALID_OPERATIONREAD_ERRORNO_DATA_FOUNDVALUE_ERROR
This procedure reads text from the open file identified by the file handle and places the text in the output buffer parameter. With this function, you can read a text file in Unicode instead of in the database charset. See also "GET_LINE Procedure".
UTL_FILE.GET_LINE_NCHAR ( file IN FILE_TYPE, buffer OUT NVARCHAR2, len IN PLS_INTEGER DEFAULT NULL);
This function reads a RAW string value from a file and adjusts the file pointer ahead by the number of bytes read.
UTL_FILE.GET_RAW ( fid IN utl_file.file_type, r OUT NOCOPY RAW, len IN PLS_INTEGER DEFAULT NULL);
| Parameters | Description |
|---|---|
|
fid |
The file ID. |
|
r |
The |
|
len |
The number of bytes read from the file. Default is |
PUT writes the text string stored in the buffer parameter to the open file identified by the file handle. The file must be open for write operations. No line terminator is appended by PUT; use NEW_LINE to terminate the line or use PUT_LINE to write a complete line with a line terminator. See also "PUT_NCHAR Procedure".
The maximum size of the buffer parameter is 32767 bytes unless you specify a smaller size in FOPEN. The default is approximately 1000 bytes, depending on your platform. The sum of all sequential PUT calls cannot exceed 32767 without intermediate buffer flushes.
UTL_FILE.PUT ( file IN FILE_TYPE, buffer IN VARCHAR2);
INVALID_FILEHANDLEINVALID_OPERATIONWRITE_ERROR
This procedure writes the text string stored in the buffer parameter to the open file identified by the file handle. With this function, you can write a text file in Unicode instead of in the database charset. See also "PUT Procedure".
The maximum size of the buffer parameter is 32767 bytes unless you specify a smaller size in FOPEN. The default is approximately 1000 bytes, depending on your platform. The sum of all sequential PUT calls cannot exceed 32767 without intermediate buffer flushes.
UTL_FILE.PUT_INCHAR ( file IN FILE_TYPE, buffer IN NVARCHAR2);
This function accepts as input a RAW data value and writes the value to the output buffer. You can request an automatic flush of the buffer by setting the third argument to TRUE.
The maximum size of the buffer parameter is 32767 bytes unless you specify a smaller size in FOPEN. The default is approximately 1000 bytes, depending on your platform. The sum of all sequential PUT calls cannot exceed 32767 without intermediate buffer flushes.
UTL_FILE. PUT_RAW ( fid IN utl_file.file_type, r IN RAW, autoflush IN BOOLEAN DEFAULT FALSE);
| Parameters | Description |
|---|---|
|
fid (IN) |
The file ID. |
|
r (IN) |
The |
|
autoflush (IN) |
If |
This procedure writes one or more line terminators to the file identified by the input file handle. This procedure is separate from PUT because the line terminator is a platform-specific character or sequence of characters.
UTL_FILE.NEW_LINE ( file IN FILE_TYPE, lines IN NATURAL := 1);
| Parameters | Description |
|---|---|
|
file |
Active file handle returned by an |
|
lines |
Number of line terminators to be written to the file. |
INVALID_FILEHANDLEINVALID_OPERATIONWRITE_ERROR
This procedure writes the text string stored in the buffer parameter to the open file identified by the file handle. The file must be open for write operations. PUT_LINE terminates the line with the platform-specific line terminator character or characters.
The maximum size of the buffer parameter is 32767 bytes unless you specify a smaller size in FOPEN. The default is approximately 1000 bytes, depending on your platform. The sum of all sequential PUT calls cannot exceed 32767 without intermediate buffer flushes.
See also "PUT_LINE_NCHAR Procedure".
UTL_FILE.PUT_LINE ( file IN FILE_TYPE, buffer IN VARCHAR2, autoflush IN BOOLEAN DEFAULT FALSE);
| Parameters | Description |
|---|---|
|
file |
Active file handle returned by an |
|
buffer |
Text buffer that contains the lines to be written to the file. |
|
autoflush |
Flushes the buffer to disk after the |
INVALID_FILEHANDLEINVALID_OPERATIONWRITE_ERROR
This procedure writes the text string stored in the buffer parameter to the open file identified by the file handle. With this function, you can write a text file in Unicode instead of in the database charset. See also "PUT_LINE Procedure".
The maximum size of the buffer parameter is 32767 bytes unless you specify a smaller size in FOPEN. The default is approximately 1000 bytes, depending on your platform. The sum of all sequential PUT calls cannot exceed 32767 without intermediate buffer flushes.
UTL_FILE.PUT_LINE_NCHAR ( file IN FILE_TYPE, buffer IN NVARCHAR2);
This procedure is a formatted PUT procedure. It works like a limited printf(). The format string can contain any text, but the character sequences %s and \n have special meaning.
| Character Sequence | Meaning |
|---|---|
|
%s |
Substitute this sequence with the string value of the next argument in the argument list. |
|
\n |
Substitute with the appropriate platform-specific line terminator. |
See also "PUTF_NCHAR Procedure".
UTL_FILE.PUTF ( file IN FILE_TYPE, format IN VARCHAR2, [arg1 IN VARCHAR2 DEFAULT NULL, . . . arg5 IN VARCHAR2 DEFAULT NULL]);
The following example writes the lines:
Hello, world! I come from Zork with greetings for all earthlings. my_world varchar2(4) := 'Zork'; ... PUTF(my_handle, 'Hello, world!\nI come from %s with %s.\n', my_world, 'greetings for all earthlings');
If there are more %s formatters in the format parameter than there are arguments, then an empty string is substituted for each %s for which there is no matching argument.
INVALID_FILEHANDLEINVALID_OPERATIONWRITE_ERROR
This procedure is a formatted PUT_NCHAR procedure. With this function, you can write a text file in Unicode instead of in the database charset. See also "PUTF Procedure". See also "PUT_LINE Procedure".
The maximum size of the buffer parameter is 32767 bytes unless you specify a smaller size in FOPEN. The default is approximately 1000 bytes, depending on your platform. The sum of all sequential PUT calls cannot exceed 32767 without intermediate buffer flushes.
UTL_FILE.PUTF_NCHAR ( file IN FILE_TYPE, format IN NVARCHAR2, [arg1 IN NVARCHAR2 DEFAULT NULL, . . . arg5 IN NVARCHAR2 DEFAULT NULL]);
FFLUSH physically writes pending data to the file identified by the file handle. Normally, data being written to a file is buffered. The FFLUSH procedure forces the buffered data to be written to the file. The data must be terminated with a newline character.
Flushing is useful when the file must be read while still open. For example, debugging messages can be flushed to the file so that they can be read immediately.
UTL_FILE.FFLUSH ( file IN FILE_TYPE); invalid_maxlinesize EXCEPTION;
| Parameters | Description |
|---|---|
|
file |
Active file handle returned by an |
INVALID_FILEHANDLEINVALID_OPERATIONWRITE_ERROR
This function adjusts the file pointer forward or backward within the file by the number of bytes specified.
If offset, the function seeks to a byte offset. If the end of the file or the beginning of the file is reached before seeking is done, the function returns the last or first row, respectively.
If loc, the function seeks to an absolute location specified in bytes.
UTL_FILE.FSEEK ( fid IN utl_file.file_type, absolute_offset IN PL_INTEGER DEFAULT NULL, relative_offset IN PLS_INTEGER DEFAULT NULL);
Using this function, you can read previous lines in the file without first closing and reopening the file. You must know the number of bytes by which you want to navigate.
This function deletes a disk file, assuming that you have sufficient privileges.
UTL_FILE.FREMOVE ( location IN VARCHAR2, filename IN VARCHAR2);
| Parameters | Description |
|---|---|
|
location (IN) |
The directory location of the file, a |
|
|
The name of the file to be deleted |
The FREMOVE function does not verify privileges prior to deleting the file. The O/S verifies file and directory permissions. An exception is returned on failure.
This function copies a contiguous portion of a file to a newly created file. By default, the whole file is copied if the start_line and end_line parameters are omitted. The source file is opened in read mode. The destination file is opened in write mode. A starting and ending line number can optionally be specified to select a portion from the center of the source file for copying.
UTL_FILE.FCOPY ( location IN VARCHAR2, filename IN VARCHAR2, dest_dir IN VARCHAR2, dest_file IN VARCHAR2, start_line IN PLS_INTEGER DEFAULT 1, end_line IN PLS_INTEGER DEFAULT NULL);
This function returns the current relative offset position within a file, in bytes.
UTL_FILE.FGETPOS ( fileid IN file_type) RETURN PLS_INTEGER;
| Parameters | Description |
|---|---|
|
fileid (IN) |
The directory location of the source file |
FGETPOS returns the relative offset position for an open file, in bytes. It raises an exception if the file is not open. It returns 0 for the beginning of the file.
This procedure reads and returns the attributes of a disk file.
UTL_FILE.FGETATTR( location IN VARCHAR2, filename IN VARCHAR2, exists OUT BOOLEAN, file_length OUT NUMBER, blocksize OUT NUMBER);
This function renames an existing file to a new name, similar to the Unix mv function. Permission on both the source and destination directories must be granted. You can use the overwrite parameter to specify whether or not to overwrite a file if one exists in the destination directory. The default is FALSE for no overwrite.
UTL_FILE.FRENAME ( location IN VARCHAR2, filename IN VARCHAR2, dest_dir IN VARCHAR2, dest_file IN VARCHAR2, overwrite IN BOOLEAN DEFAULT FALSE);
|
 Copyright © 2000, 2002 Oracle Corporation. All Rights Reserved. |
|