Файловый вывод

Для вывода данных в файлы используются пять процедур: PUT, PUT_LINE, NEW_LINE, PUTF и FFLUSH. Работа процедур PUT, PUT LINE и NEW_LINE сходна с работой их аналогов, входящих в состав модуля DBMS_OUTPUT. Максимальный размер выходной записи равен 1023 байтам (если не указано иное значение в FOPEN), в том числе байт для символа новой строки.

Описание процедуры PUT в модуле UTL_FILE имеет следующий вид:

procedure PUT ( file_handle in FILE TYPE,

buffer in varchar2);

Символ новой строки в файл не вводится. Для того чтобы включить в файл признак конца строки, используются процедуры PUT_LINE или NEW_LINE. В случае ошибки записи устанавливается UTL_FILE.WRITE_ERROR. Параметры процедуры PUT описаны в следующей таблице.

Таблица 9 Параметры процедуры PUT

Параметр	Тип	Описание
file_handle	UTL_FILE.FILE_TYPE	Описатель файла, возвращаемый функцией FOPEN. Если описатель некорректен, то устанавливается UTL_FILE.INVALID_FILEHANDLE.
buffer	varchar2	Текстовая строка символов, выводимая в файл. Если файл не был открыт в режиме ‘w’ или ‘а’, то устанавливается UTL_FILE.INVALID_OPERATION.

Процедура NEW_LINE записывает один или несколько признаков конца строки в указанный файл:

procedure NEW_LINE (file_handle in FILE_TYPE, lines in natural := 1);

Признак конца строки зависит от используемой системы – в разных операционных системах признаки конца строки различны. В случае ошибки записи устанавливается UTL_FILE.WRITЕ_ERROR. Параметры процедуры описаны в следующей таблице:

Таблица 10 Параметры процедуры NEW_LINE

Параметр	Тип	Описание
file_handle	UTL_FILE.FILE_TYPE	Описатель файла, возвращаемый функцией FOPEN. Если описатель некорректен, то устанавливается UTL_FILE.INVALID_FILEHANDLE.
lines	natural	Число выводимых признаков конца строки. Значение по умолчанию равно 1, что соответствует выводу одного символа новой строки. Если файл не был открыт в режиме ‘w’ или ‘а’, то устанавливается UTL_FILE.INVALID_OPERATION.

Процедура PUT_LINE выводит указанную последовательность символов в указанный файл, причем данный файл должен быть открыт на запись. После вывода последовательности выводится символ новой строки, определяемый используемой платформой:

procedure PUT_LINE (file handle in FILE_TYPE, buffer in varchar2);

Процедура PUTF подобна PUT, но позволяет форматировать выходную строку символов. PUTF – это сокращенный вариант функции printf(), применяемой в языке С, и имеет аналогичный синтаксис:

procedure PUTF (file_handle in FILE TYPE, format in varchar2,

arg1 in varchar2 default null,

arg2 in varchar2 default null,

arg3 in varchar2 default null,

arg4 in varchar2 default null,

arg5 in varchar2 default null);

Заметим, что аргументы с ARG1 по ARG5 имеют значения по умолчанию, то есть они необязательны. В строке FORMAT содержится обычный текст плюс два специальных символа %s и \n. Каждый экземпляр %s в этой строке замещается одним из необязательных аргументов, а каждый экземпляр \n – символом новой строки. В случае ошибки записи устанавливается UTL_FILE.WRITE_ERROR.

С помощью процедур PUT, PUT_LINE, PUTF и NEW_LINE данные выводятся через буфер. Когда буфер заполняется, данные физически сбрасываются (flush) в файл. Процедура FFLUSH записывает содержимое буфера в файл немедленно, причем выводятся только те строки буфера, которые заканчиваются символом перевода строки, все данные, записанные последними операциями PUT, остаются в буфере. Описание этой процедуры выглядит следующим образом:

procedure FFLUSH (file_handle in FILE_TYPE).