XCVI. Функции для работы с Oracle

Введение

Эти функции позволяют вам работать с Oracle версий 9/8/7. Для этого используется библиотека Oracle Call Interface (OCI).

Данный модуль много гибче прежнего. Он содержит функции привязки переменных PHP к соответствующим меткам Oracle, расширенную поддержка LOB, FILE и ROWID. Использование этого модуля рекомендуется вместо старого модуля.

Требования

Вам понадобятся клиентские библиотеки Oracle для того, чтобы использовать этот модуль. Пользователям Windows будет необходим Oracle версии минимум 8.1 для того, чтобы использовать php_oci8.dll.

Перед использованием этого модуля, проверьте, что вы установили все необходимые переменные окружения. Эти переменные, перечисленные ниже, должны быть доступны пользователю Oracle и пользователю, с правами которого работает веб-сервер. Переменные окружения, необходимые для корректной работы с Oracle:

ORACLE_HOME
ORACLE_SID
LD_PRELOAD
LD_LIBRARY_PATH
NLS_LANG
ORA_NLS33

После установки среды окружения для веб-сервера, добавьте пользователя, с правами которого работает веб-сервер, в группу oracle.

Если ваш веб-сервер не стартует или возвращает ошибку при старте: Проверьте, что Apache был слинкован с библиотекой pthread:
# ldd /www/apache/bin/httpd 
libpthread.so.0 => /lib/libpthread.so.0 (0x4001c000)
libm.so.6 => /lib/libm.so.6 (0x4002f000)
libcrypt.so.1 => /lib/libcrypt.so.1 (0x4004c000)
libdl.so.2 => /lib/libdl.so.2 (0x4007a000)
libc.so.6 => /lib/libc.so.6 (0x4007e000)
/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
Если libpthread не присутствует в списке, то вам придется переустановить Apache:
# cd /usr/src/apache_1.3.xx
# make clean
# LIBS=-lpthread ./config.status
# make
# make install
Обратите внимание на то, что на некоторых системах, например, UnixWare, вместо libthread присутствует libpthread. PHP и Apache также должны быть собраны с EXTRA_LIBS=-lthread.

Установка

PHP должен быть сконфигурирован с опцией --with-oci8[=DIR], где DIR соответствует директории, в которой находится установленный ранее сервер и/или клиент Oracle. По умолчанию значение DIR соответствует переменной окружения ORACLE_HOME.

Если вы используете Oracle Instant Client, то для поддержки модуля OCI8 нужно, чтобы PHP был сконфигурирован с опцией --with-oci8-instant-client[=DIR]. Обратите внимание: поддержка Oracle Instant Client появилась только начиная с версий 4.3.11 и 5.0.4.

Настройка во время выполнения

Данное расширение не определяет никакие директивы конфигурации в php.ini.

Типы ресурсов

Предопределенные константы

Перечисленные ниже константы определены данным расширением и могут быть доступны только в том случае, если PHP был собран с поддержкой этого расширения или же в том случае, если данное расширение подгружается во время выполнения.

OCI_DEFAULT (integer): Режим выполнения выражения SQL. В этом режиме транзакция не завершается автоматически оператором COMMIT.
OCI_DESCRIBE_ONLY (integer): Режим выполнения выражения SQL. Используйте этот режим, если вы хотите получить данные о выполнении запроса, а не выполнить сам запрос.
OCI_COMMIT_ON_SUCCESS (integer): Режим выполнения выражения SQL. Транзакция автоматически завершается вызовом оператора COMMIT после выполнения oci_execute().
OCI_EXACT_FETCH (integer): Режим получения результатов запроса. Используется в том случае, если приложению известно заранее сколько строк будет получено в результате. Oracle 8 и более поздние версии не используют выборку результатов с упреждением в этом режиме, а курсоры уничтожаются автоматически после выборки ожидаемого количества строк, что может уменьшить требования сервера к ресурсам.
OCI_SYSDATE (integer)
OCI_B_BFILE (integer): Используется функцией oci_bind_by_name() для привязки переменных типа BFILE.
OCI_B_CFILEE (integer): Используется функцией oci_bind_by_name() для привязки переменных типа CFILE.
OCI_B_CLOB (integer): Используется функцией oci_bind_by_name() для привязки переменных типа CLOB.
OCI_B_BLOB (integer): Используется функцией oci_bind_by_name() для привязки переменных типа BLOB.
OCI_B_ROWID (integer): Используется функцией oci_bind_by_name() для привязки переменных типа ROWID.
OCI_B_CURSOR (integer): Используется функцией oci_bind_by_name() для привязки курсоров, созданных ранее с помощью oci_new_cursor().
OCI_B_NTY (integer): Используется функцией oci_bind_by_name() для привязки именованных типов данных. В PHP < 5.0 эта константа называлась OCI_B_SQLT_NTY.
OCI_B_BIN (integer)
SQLT_BFILEE (integer): То же, что и OCI_B_BFILE.
SQLT_CFILEE (integer): То же, что и OCI_B_CFILEE.
SQLT_CLOB (integer): То же, что и OCI_B_CLOB.
SQLT_BLOB (integer): То же, что и OCI_B_BLOB.
SQLT_RDD (integer): То же, что и OCI_B_ROWID.
SQLT_NTY (integer): То же, что и OCI_B_NTY.
OCI_FETCHSTATEMENT_BY_COLUMN (integer): Режим oci_fetch_all() по умолчанию.
OCI_FETCHSTATEMENT_BY_ROW (integer): Альтернативный режим oci_fetch_all().
OCI_ASSOC (integer): Используется с oci_fetch_all() и oci_fetch_array() для получения ассоциативного массива.
OCI_NUM (integer): Используется с oci_fetch_all() и oci_fetch_array() для получения массива с числовыми индексами.
OCI_BOTH (integer): Используется с oci_fetch_all() и oci_fetch_array() для получения массива с ассоциативными и числовыми индексами.
OCI_RETURN_NULLS (integer): Используется с oci_fetch_array() для получения пустых элементов массива, если соответствующее поле в результате равно NULL.
OCI_RETURN_LOBS (integer): Используется oci_fetch_array() для получения содержания объекта LOB вместо дескриптора.
OCI_DTYPE_FILE (integer): Флаг используется oci_new_descriptor() для инициализации дескриптора типа FILE.
OCI_DTYPE_LOB (integer): Флаг используется oci_new_descriptor() для инициализации дескриптора типа LOB.
OCI_DTYPE_ROWID (integer): Флаг используется oci_new_descriptor() для инициализации дескриптора типа ROWID.
OCI_D_FILE (integer): То же, что и OCI_DTYPE_FILE.
OCI_D_LOB (integer): То же, что и OCI_DTYPE_LOB.
OCI_D_ROWID (integer): То же, что и OCI_DTYPE_ROWID.

Примеры

Пример 1. Примеры использования
<?php // by sergo at bacup dot ru // Use option: OCI_DEFAULT for execute command to delay execution OCIExecute($stmt, OCI_DEFAULT); // for retrieve data use (after fetch): $result = OCIResult($stmt, $n); if (is_object($result)) $result = $result->load(); // For INSERT or UPDATE statement use: $sql = "insert into table (field1, field2) values (field1 = 'value', field2 = empty_clob()) returning field2 into :field2"; OCIParse($conn, $sql); $clob = OCINewDescriptor($conn, OCI_D_LOB); OCIBindByName($stmt, ":field2", &$clob, -1, OCI_B_CLOB); OCIExecute($stmt, OCI_DEFAULT); $clob->save("some text"); OCICommit($conn); ?>

Вы можете использовать хранимые процедуры так же, как это делается из командной строки.
Пример 2. Использование хранимых процедур
<?php // by webmaster at remoterealty dot com $sth = OCIParse($dbh, "begin sp_newaddress( :address_id, '$firstname', '$lastname', '$company', '$address1', '$address2', '$city', '$state', '$postalcode', '$country', :error_code );end;"); // This calls stored procedure sp_newaddress, with :address_id being an // in/out variable and :error_code being an out variable. // Then you do the binding: OCIBindByName($sth, ":address_id", $addr_id, 10); OCIBindByName($sth, ":error_code", $errorcode, 10); OCIExecute($sth); ?>

Содержание
OCI-Collection->append -- Appends element to the collection
OCI-Collection->assign -- Assigns a value to the collection from another existing collection
OCI-Collection->assignElem -- Assigns a value to the element of the collection
OCI-Collection->free -- Frees the resources associated with the collection object
OCI-Collection->getElem -- Returns value of the element
OCI-Collection->max -- Returns the maximum number of elements in the collection
OCI-Collection->size -- Returns size of the collection
OCI-Collection->trim -- Trims elements from the end of the collection
OCI-Lob->append -- Appends data from the large object to another large object
OCI-Lob->close -- Closes LOB descriptor
OCI-Lob->eof -- Tests for end-of-file on a large object's descriptor
OCI-Lob->erase -- Erases a specified portion of the internal LOB data
OCI-Lob->export -- Exports LOB's contents to a file
OCI-Lob->flush -- Flushes/writes buffer of the LOB to the server
OCI-Lob->free -- Frees resources associated with the LOB descriptor
OCI-Lob->getBuffering -- Returns current state of buffering for the large object
OCI-Lob->import -- Imports file data to the LOB
OCI-Lob->load -- Returns large object's contents
OCI-Lob->read -- Reads part of the large object
OCI-Lob->rewind -- Moves the internal pointer to the beginning of the large object
OCI-Lob->save -- Saves data to the large object
OCI-Lob->saveFile -- Alias of oci_lob_import()
OCI-Lob->seek -- Sets the internal pointer of the large object
OCI-Lob->setBuffering -- Changes current state of buffering for the large object
OCI-Lob->size -- Returns size of large object
OCI-Lob->tell -- Returns current position of internal pointer of large object
OCI-Lob->truncate -- Truncates large object
OCI-Lob->write -- Writes data to the large object
OCI-Lob->writeTemporary -- Writes temporary large object
OCI-Lob->writeToFile -- Alias of oci_lob_export()
oci_bind_by_name -- Привязывает переменную PHP к соответствующей метке в SQL-выражении.
oci_cancel -- Заканчивает процесс чтения из курсора
oci_close -- Закрывает соединение с сервером Oracle
oci_commit -- Завершает и подтверждает транзакцию
oci_connect -- Устанавливает соединение с сервером Oracle
oci_define_by_name -- Определяет переменную PHP, в которую будет возвращено соответствующее поле из результата
oci_error -- Возвращает последнюю ошибку
oci_execute -- Выполняет выражение SQL
oci_fetch_all -- Выбирает все строки из результата запроса в массив
oci_fetch_array -- Возвращает следующую строку из результата запроса в виде ассоциативного массива, числового массива или оба сразу
oci_fetch_assoc -- Возвращает следующую строку из результата запроса в виде ассоциативного массива
oci_fetch_object -- Возвращает следующую строку из результата запроса в виде объекта
oci_fetch_row -- Возвращает следующую строку из результата запроса в виде массива с числовыми индексами
oci_fetch -- Выбирает следующую строку из результата в буфер
oci_field_is_null -- Проверяет, равняется ли поле NULL
oci_field_name -- Возвращает имя поля из результата запроса
oci_field_precision -- Возвращает точность поля
oci_field_scale -- Возвращает масштаб поля
oci_field_size -- Возвращает размер поля
oci_field_type_raw -- Возвращает тип исходный тип поля
oci_field_type -- Возвращает тип поля
oci_free_statement -- Освобождает ресурсы, занимаемые курсором или SQL-выражением
oci_internal_debug -- Включает и выключает внутреннюю отладку
oci_lob_copy -- Копирует содержание или часть содержания одного объекта LOB в другой
oci_lob_is_equal -- Сравнивает два объекта LOB
oci_new_collection -- Создает новый объект коллекции
oci_new_connect -- Устанавливает новое соединение с сервером Oracle
oci_new_cursor -- Возвращает идентификатор созданного курсора
oci_new_descriptor -- Инициализирует новый дескриптор объекта LOB или FILE
oci_num_fields -- Возвращает количество полей в результате запроса
oci_num_rows -- Возвращает количество строк, измененных в процессе выполнения запроса
oci_parse -- Подготавливает запрос к выполнению
oci_password_change -- Изменяет пароль пользователя Oracle
oci_pconnect -- Устанавливает постоянное соединение с сервером Oracle
oci_result -- Возвращает значение поля из результата запроса
oci_rollback -- Откатывает транзакции, ожидающие обработки
oci_server_version -- Возвращает строку с информацией о версии сервера Oracle
oci_set_prefetch -- Устанавливает количество строк, которые будут автоматически выбраны в буфер
oci_statement_type -- Возвращает тип выражения
ocibindbyname -- Alias of oci_bind_by_name()
ocicancel -- Alias of oci_cancel()
ocicloselob -- Alias of OCI-Lob->close
ocicollappend -- Alias of OCI-Collection->append
ocicollassign -- Alias of OCI-Collection->assign
ocicollassignelem -- Alias of OCI-Collection->assignElem
ocicollgetelem -- Alias of OCI-Collection->getElem
ocicollmax -- Alias of OCI-Collection->max
ocicollsize -- Alias of OCI-Collection->size
ocicolltrim -- Alias of OCI-Collection->trim
ocicolumnisnull -- Alias of oci_field_is_null()
ocicolumnname -- Alias of oci_field_name()
ocicolumnprecision -- Alias of oci_field_precision()
ocicolumnscale -- Alias of oci_field_scale()
ocicolumnsize -- Alias of oci_field_size()
ocicolumntype -- Alias of oci_field_type()
ocicolumntyperaw -- Alias of oci_field_type_raw()
ocicommit -- Alias of oci_commit()
ocidefinebyname -- Alias of oci_define_by_name()
ocierror -- Alias of oci_error()
ociexecute -- Alias of oci_execute()
ocifetch -- Alias of oci_fetch()
ocifetchinto -- Выбирает следующую строку из результата запроса в массив
ocifetchstatement -- Выбирает все строки из результата запроса в массив
ocifreecollection -- Alias of OCI-Collection->free
ocifreecursor -- Alias of oci_free_statement()
ocifreedesc -- Alias of OCI-Lob->free
ocifreestatement -- Alias of oci_free_statement()
ociinternaldebug -- Alias of oci_internal_debug()
ociloadlob -- Alias of OCI-Lob->load
ocilogoff -- Alias of oci_close()
ocilogon -- Alias of oci_connect()
ocinewcollection -- Alias of oci_new_collection()
ocinewcursor -- Alias of oci_new_cursor()
ocinewscriptor -- Alias of oci_new_descriptor()
ocinlogon -- Alias of oci_new_connect()
ocinumcols -- Alias of oci_num_fields()
ociparse -- Alias of oci_parse()
ociplogon -- Alias of oci_pconnect()
ociresult -- Alias of oci_result()
ocirollback -- Alias of oci_rollback()
ocirowcount -- Alias of oci_num_rows()
ocisavelob -- Alias of OCI-Lob->save
ocisavelobfile -- Alias of OCI-Lob->import
ociserverversion -- Alias of oci_server_version()
ocisetprefetch -- Alias of oci_set_prefetch()
ocistatementtype -- Alias of oci_statement_type()
ociwritelobtofile -- Alias of OCI-Lob->export
ociwritetemporarylob -- Alias of OCI-Lob->writeTemporary