Stfw.RuODBC
Взаимодействие с базами данных
🕛 01.11.2006, 13:54
В дополнение к поддержке обычных драйверов ODBC, данная группа функций позволяет работать с базами данных, поддерживающими так называемый интерфейс Unified ODBC. В число БД, использующих API Unified ODBC, входят: Adabas D (http://www.adabas.com), IBM DB2 (http://www.ibm.com/db2), iODBC (http://www.iodbc.org), Solid (http://www.solidtech.com) и Sybase SQL Anywhere (http://www. sybase.com). Схемы работы с различными БД практически идентичны и различаются только в отношении внутреннего функционирования серверов БД.
См. также раздел «Инсталляция в системах Unix» относительно конфигурирования поддержки этих БД при компиляции.
Заметьте, что использование драйверов ODBC снижает производительность и не является оправданным, если, конечно, вы не планируете менять БД вашего приложения достаточно часто. Более обоснованно использовать первичные функции РНР интерфейса соответствующей БД.
Но что касается БД с интерфейсом Unified ODBC, то здесь не используются сами ODBC драйверы, просто все они используют единую архитектуру API, аналогичную ODBC.
odbc_connect
Подключение к источнику данных (БД)
int odbc_connect (string dsn. string user, string password [, int cursor J:ype])
Возвращает дескриптор подключения к БД (используемый последующими функциями) или О (FALSE) при ошибке. Одновременно можно открывать несколько подключений. В общем случае для открытия подключения необходимо указывать имя системного источника данных DSN, имя и пароль клиента. В Unix-системах иногда возникает проблема подключений, которая может быть устранена указали-
ем параметров подключения в одной строке аргумента dsn в виде
«DSN=DataSource:UID=UserName;PWD=Password».
В необязательном четвертом аргументе можно указать тип курсора БД, и это часто помогает решить проблемы с некоторыми БД; например, при попытке выполнения хранимых процедур (при вызове которых возникает ошибка типа: "Cannot open a cursor on a stored procedure that has anything other than a single select statement in it"), и в таких случаях может помочь указание типа курсора SQL_CUR_ USE_ODBC. Тип курсора может быть указан одной из следующих констант:
SQL_CUR_USE_IF_NEEDED;
SQL_CUR_USE_ODBC;
SQL_CUR_USE_DRIVER;
SQL_CUR_DEFAULT.
odbc_pconnect
Создание устойчивого подключения
int odbc_pconnect (string dsn, string user, string password [, \ int cursor_type])
Возвращает дескриптор подключения к БД или FALSE - при ошибке.
Перед подключением функция пытается проверить, имеется ли уже открытое (устойчивое) подключение с параметрами (имя источника данных, пользователя и пароль), аналогичными указанным. Если такое подключение обнаруживается, то возвращается его идентификатор вместо создания нового подключения.
При завершении сценария подключение не закрывается, а остается действительным для дальнейшего использования. Но устойчивые подключения не работают, если РНР запускается в режиме CGI.
odbc_close
Закрытие сеанса подключения ODBC
void odbc_close (int connection_id)
Заметьте, при имеющихся незавершенных транзакциях функция не закрывает подключение.
odbc_close_all
Закрытие всех подключений ODBC
void odbc_close_aTI(void);
odbc_cursor
Определение типа курсора для подключения
string odbc_cursor (int result_id)
Возвращает имя курсора, используемого в подключении result_ld.
odbc_do
Синоним odbc_exec
int odbc_do (int conn_id, string query)
odbc_exec
Выполнение запроса SQL
int odbc_exec (int connection_id, string query_string)
Возвращает дескриптор набора записей, возвращенных запросом query_string, или FALSE - при ошибке. Параметр connectionjid должен быть ранее успешно возвращен функцией odbc_connect() или odbc_pconnect().
См. также: odbc_prepare() и odbc_execute().
odbc_prepare
Подготовка запроса
int odbc_prepare (int connection_id, string query_string)[
Функция возвращает дескриптор запроса, который затем исполь зуется в функции odbc_execute() для его исполнения, или FALSE - в случае ошибки.
odbc_execute
Выполнение подготовленного запроса
int odbc_execute (int result_id [, array parameters_array])
Выполняет запрос resu1t_id, подготовленный функцией odbc_prepare(). Возвращает TRUE или FALSE - при ошибке. В массиве parameters_array можно указать параметры запроса, если они требуются.
odbc_autocommit
Переключение режима транзакций autocommit
int odbc_autocommit (int connection_id [, int OnOff])
Если не указывается аргумент OnOff, функция возвращает текущее состояние auto-commit для подключения connection_id. True означает «разрешено», a FALSE - «не разрешено» или произошла ошибка.
Если в значении аргумента OnOff указывается значение TRUE, то последующие запросы исполняются незамедлительно, если FALSE - то они откладываются до вызова функции odbc_commit() (таким образом формируя транзакцию). При этом возвращается TRUE или FALSE - при ошибке.
По умолчанию вес запросы исполняются незамедлительно, и запрещение состояния auto-commit равносильно началу транзакции.
См. также: odbc_commit() и odbc_rollback().
odbc_commit
Завершение транзакции
int odbc_commit (int connectiorMd)
Выполняет все отложенные запросы (транзакцию) для подключения connectiorMd и возвращает TRUE или FALSE - при ошибке.
odbc_rollback
Отмена транзакции
int odbc_rollback (int connection_id)
Отменяет псе отложенные запросы (транзакцию) для подключения connection_id и возвращает TRUE или FALSE - при ошибке.
odbc_num_rows
Получение числа возвращенных записей
int odbc_num_rows (int resulted)
; В аргументе указывается дескриптор результата, возвращенный ODBC ' запросом. При ошибке возвращается -1. Для запросов INSERT, UPDATE и DELETE возвращается число вставленных, измененных, удаленных записей; для запроса SELECT - число возвращенных запросом записей (некоторые драйверы возвращают -1 вне зависимости от того, сколько записей было возвращено).
odbc_num_fields
Определение числа полей в результате
int odbc_num_fields (int result_id)
В аргументе указывается дескриптор результата, возвращенный ODBC запросом (функцией odbc_exec()). Функция возвращает число полей (столбцов), содержащихся в наборе записей, возвращенных запросом, либо -1 в случае ошибки.
Обработка полей LONGVARBINARY определяется odbc_binmode().
odbc_result
Получение данных результата запроса
string odbc_result (int result_id, mixed field)
Возвращает содержимое поля, указанного аргументом field текущей записи. Поле может быть указано номером (начиная с 1) или именем:
$item_3 = odbc_result ($Query_ID. 3);
$item_val = odbc_result ($Query_ID. "id"):
Данные полей типа long или двоичные данные возвращаются согласно установкам функций odbc_binmode() и odbcJongreadlen().
odbc_result_all
Распечатка результата запроса в таблице HTML
int odbc_result_all (int result_id [. string format])
Возвращает число выведенных записей или FALSE - при ошибке. В аргументе result_id указывается дескриптор набора записей, возвращенный функцией odbc_exec(), а в строке format можно указать атрибуты тега <TABLE ... >.
odbc_fetch_row
Установка курсора текущей записи
int odbc_fetch_row (int resu!t_id [, int rowjiumber])
Выбирает запись номер rowjiumber (или по умолчанию следующую) . из набора записей resultjid, возвращенного функциями odbc_do() или odbcjaxec(). Возвращает TRUE или FALSE - при ошибке (например, когда записи с таким номером не существует). Последующие вызовы odbc_result() будут возвращать данные из выбранной записи. Нумерация начинается с 0. Не все драйверы допускают произвольный выбор записи.
$сnn = odbc_conrect
("MyDSN"."root" "passI23"):
$rs = odbcjBxecdcnn. "SELECT * FROM tbll").
echo "Записей. ".
$nr = odbc_num_rows($rs).
echo ".иполей: ".
$nf - odbc_num_fields($rs);
// распечатать в виде [n]
'aaa'. '666'. 'ввв'. for($r=l; $r<=$nr; $r++)
{ // записи echo "\n[$r] ".
odbc_fetch_row($rs.$r).
for($f=l: $f<=$nf: $f++)
// поля echo "'",
odbc result(Srs.$f). "'.": }
odbc_fetch_into
Занесение полученной записи в массив
int odbc_fetch_into (int result id [, int rownumber. array resu"lt_array])
Заносит поля записи номер rownumber из набора записей result_id в элементы массива resu"lt_array. Возвращает число полей набора записей (результата запроса) или FALSE - при ошибке.
$cnn = odbc_connect
( 'MyDSN"."root"."pass!23").
$rs = odbc_exec
($cnn."SELECT * FROM tbll").
for($r=l; $r<=odbc_num_rows
($rs): $r++) { odbc_fetch_into($rs.$r.$arr):
$ar[]=$arr
// занести набор записей в двухмерный массив
odbc_ field_name
Определение имени поля
string odbc_field_name (int result_id, int field_number)
Возвращает имя поля по его номеру field_number в наборе записей result_id. Нумерация начинается с 1. При ошибке возвращает FALSE.
odbc_field_num
Определение порядкового номера поля
int odbc_field_num (int result_id, string field_name)
Возвращает номер поля по его имени field_name в наборе записей result_id. Нумерация начинается с 1. При ошибке возвращает FALSE.
odbc_field_type
Получение типа данных поля
string odbc_field_type (int resulted, int fieldjiumber)
Возвращает SQL-тип поля с номером field_number в наборе записей result_id. Нумерация начинается с 1. При ошибке возвращает FALSE.
odbc_field_len
Получение длины (точности) поля
int odbc_field_len (int resultjid, int fieldjiumber)
См. также: odbc_field_scale().
odbc_field_precision
Синоним odbc_fieldjen()
string odbc_field_precision (int result_id, int field_number)
odbc_field_scale
Определение точности поля
string odbc_field_scale (int result_id, int field_number)
Функция возвращает число сохраняемых десятичных знаков после запятой для полей дробных чисел.
odbc_free_result
Освобождение ресурсов, занятых набором записей
int odbcjreej-esult (Int result_id)
Всегда возвращает TRUE. Поскольку при завершении сценария освобождаются вес выделенные ему ресурсы, использовать данную функцию имеет смысл только в случае крайней экономии памяти, расходуемой сценарием.
Если транзакция была начата, но не завершена (см. odbc_autocommit()), данная функция отменяет ее.
odbc_binmode
Определение обработки двоичных полей
int odbc_binmode (int result_id, int mode)
Функция управляет обработкой полей ODBC SQL типов BINARY, VARBINARY, LONGVARBINARY. Если resultjd равен О, то установки будут применяться к новым наборам записей.
ODBC_BINMODE_PASSTHRU - пропускать двоичные поля;
ODBC_BINMODE_RETURN - возвращать двоичные поля как есть (по умолчанию); ,
ODBC_BINMODE_CONVERT - возвращать двоичные поля, конвертируя.
Пропуск (в нервом случае) означает, что при использовании функции odbc_fetch_into() для полей этого типа будет возвращаться nycтая строка.
В последнем случае конвертация означает, что каждый байт данных будет представлен двумя шестнадцатсричными цифрами, например, двоичный байт 00000001 будет представлен как "01", а 11111111 - как "FF".
Обработка длинных двоичных полей также зависит от параметра, установленного функцией odbcJongreadlen().
Binmode longreadlen Результат
ODBC BINMODE PASSTHRU 0 Пропускать
ODBC BINMODE RETURN 0 Пропускать
ODBC_BINMODE_CONVERT 0 Пропускать
ODBC BINMODE PASSTHRU >0 Пропускать
ODBC BINMODE RETURN >0 Возвращать как есть
ODBC BINMODE CONVERT >0 Конвертировать
odbc_longreadlen
Обработка полей LONG
int odbc_longreadlen (int result_id, Int length)
Функция управляет обработкой полей ODBC SQL типов LONG, LONGVARBINARY. В аргументе length указывается, сколько байтов следует возвращать из полей данных типов. По .умолчанию возвращается 4096 байтов.
См. также odbc_binmode().
odbc_setoption
Настройка параметров ODBC
int odbc_setoption (int id. int function, int option, int parara)
Если в аргументе function указывается значение 1, то тогда настраиваются параметры подключения (в этом случае в аргументе id необходимо указывать дескриптор подключения); если указывается 2, то настраиваются параметры запроса (тогда в id указывается настраиваемый запрос).
Это позволяет устранить проблемы с некоторыми своеобразными драйверами ODBC. Конечно, вы должны понимать, какой эффект будет иметь установка того или иного параметра для конкретного драйвера. Пользуйтесь документацией ODBC и не забывайте, что 1 функциональность различных версий драйверов может различаться.
Так как использование этой функции сильно зависит от специфики ODBC драйвера, использовать ее в публикуемых сценариях РНР не рекомендуется. Имейте также в виду, что некоторые параметры доступны только после открытия подключения или подготовки запроса.
Аргумент option - номер устанавливаемого параметра, а рагат - ее значение.
При ошибке возвращается FALSE; иначе TRUE.
// Номер параметра SQL_AUTOCOMM!T
в SQLSetConnectOptionO: 102
// Значение 1 для
SQL_AUTOCOMMIT - SQL_AUTOCOMMIT_ON.
// Следующая строка имеет тот же эффект, что и
// odbc_autocorrmit($conn. TRUE);
odbc_setoption (Sconn. 1. 102. 1):
// Номер параметра SQL_QUERY_TIMCOUT
в SQLSetStmtOption(): 0
// Следующая строка устанавливает
предел выполнения запроса в 30 сек.
tresult = odbc_prepare ($conn. $sq!):
odbc_setoption (Sresult. 2. 0. 30). odbc_execute
(Sresult):
odbc_tables
Получение списка таблиц источника данных
int odbc_tables (Int connection_id [, string qualifier [,
string owner [, string name [, string table_type>)
Возвращает в наборе записей перечисление имеющихся в источнике данных connection_id таблиц (определенного типа table_type). Возвращаемый набор записей содержит следующие ноля:
TABLE_QUALIFIER;
TABLE_OWNER;
TABLE_NAME - имя таблицы;
TABLE_TYPE - тип таблицы; например, «TABLE», «VIEW»;
REMARKS - примечания; например, «MySQL table».
Возвращаемый набор записей сортируется в порядке: TABLE_TYPE, TABLE_ QUALIFIER, TABLEJJWNER, TABLE_NAME.
Аргументы owner и name могут содержать шаблоны («%» заменяет ноль и более символов, а «_» - один символ).
Чтобы получить перечисление возможных значений аргументов qua- / li-ficr, owner и table type, используется следующая семантика:
Если qualifier = "%", a owner и name - пустые строки, то возвраща- \ ется набор записей, содержащий перечисление возможных квали-фикаторов источника данных. (Все поля, за исключением TABLE_ QUALIFIER содержат пустые значения NULL.) Обычно это каталоги (БД), но не все БД используют их.
Если owner = "%", a qualifier и name - пустые строки, то возвращается набор записей, содержащий перечисление владельцев источника данных. (Все поля, за исключением TABLE_OWNER, содержат пустые значения NULL.)
Если tablejtype = "%", a qualifier, owner и name - пустые строки, то возвращается набор записей, содержащий перечисление возможных типов таблиц источника данных. (Все поля, за исключением TABLE_TYPE, содержат пустые значения NULL.)
Если table_type не пустая строка, то она должна содержать перечисление через запятую типов запрашиваемых таблиц, (например, в виде: «'TABLE1.'VIEW'» или «TABLE, VIEW»).
$rs = odbc_tables($cnn. "".""."%". 'TABLF" ):
// все имеющиеся таблицы
См. также odbc_tableprivileges().
odbc_tableprivileges
Получение списка привилегий таблиц
int odbc_tableprivileges (int connect1on_id [, string qualifier [, string owner [, string name]]])
Возвращает список таблиц и присвоенных им привилегий в наборе записей или FALSE при ошибке. Возвращаемый набор записей сортируется в порядке: TA8LEJUALIFIER, TA8LE_OWNER, TABLEJAME и содержит следующие поля:
TABLE_QUALIFIER;
TABLE_OWNER;
TABLEJJAME;
GRANTOR;
GRANTEE;
PRIVILEGE;
IS_GRANTABLE.
Аргументы owner и name могут содержать шаблоны («%» заменяет .. ноль и более символов, а «_» - один символ).
См. описание odbc tables().
odbc_statistics
Получение описания таблицы
int odbc_statisties (int connection_id, string qualifier, string owner, string tablejiame, int unique, int accuracy)
Возвращает список таблиц и их индексов в наборе записей или FALSE - при ошибке. Возвращаемый набор записей сортируется в порядке: NONJJNIQUE, TYPE, INDEX_QUALIFIER, INDEXJAME и SEQ_IN_INDEX и содержит следующие ноля:
TABLE_QUALIFIER;
TABLE JMIER;
TABLE NAME;
NONJJNIQUE;
INDEX_QUALIFIER;
INDEX_NAME;
TYPE;
SEQ_IN_INDEX;
COLLATION;
CARDINALITY;
PAGES;
FILTER_CONDITION.
odbc_columns
Перечисление полей заданной таблицы
int odbc_columns (int connection_id [, string qualifier [, string owner [, string tablejiame [, string column_name>)
Возвращает список полей таблицы table_name в наборе записей или FALSE - при ошибке. Возвращаемый набор записей сортируется в порядке: TABLE_QUALIFIER, TABLE_OWNER и TABLEJAME и содержит следующие поля:
TABLE_QUALIFIER;
TABLE_OWNER;
TABLE_NAME;
COLUMN_NAME;
DATA_TYPE;
TYPE_NAME;
PRECISION;
LENGTH;
SCALE;
RADIX;
NULLABLE;
REMARKS.
Аргументы owner, tablejname и columnjiame могут содержать шаблоны («%» заменяет ноль и более символов, а «_» - один символ).
См. также odbc_columnprivileges().
odbc_columnprivileges
Перечисление полей заданной таблицы с их привилегиями
int odbc_co1umnprivileges (int connection_id [, string qualifier [, string owner [, string table_name [, string column_name>)
Возвращает список полей таблицы table_name в наборе записей или FALSE - при ошибке. Возвращаемый набор записей сортируется в порядке: TABLE_QUALIFIER, TABLE_OWNER и TABLE_NAME и содержит следующие поля:
TABLE_QUALIFIER;
TABLEJMER;
TABLE_NAME;
GRANTOR;
GRANTEE;
PRIVILEGE;
IS_GRANTABLE.
Аргумент column_name может содержать шаблоны («%» заменяет ноль и более символов, а <<_» - один символ).
odbc_gettypeinfo
Определение типов поддерживаемых данных
int odbc_gettypeinfo (Int connectien_id [, int data_type])
Возвращает набор записей, содержащий перечисление поддерживаемых БД типов данных; если необходимо выяснить, поддерживается ли конкретный тип данных, его необходимо указать в аргументе data_type. При ошибке возвращается FALSE.
А В наборе записей возвращаются следующие поля:
TYPEJIAME;
OATA_TYPE;
PRECISION;
LITERAL_PREFIX;
LITERAL_SUFFIX;
CREATE_PARAMS;
NULLABLE;
CASE_SENSITIVE;
SEARCHABLE;
UNSIGNED_AnRIBUTE;
MONEY;
AUTO_INCREMENT;
LOCAL_TYPE_NAME;
MINIMUM_SCALE;
MAXIMUM_SCALE.
Записи сортируются по полям DATA_TYPE и TYPE_NAME.
odbc_primarykeys
Подбор поля, способного быть первичным ключом таблицы
int odbc_primarykeys (int connection_id, string qualifier, string owner, string table)
Возвращает набор записей, содержащий список полей, которые могут претендовать на роль первичного ключа таблицы table. При ошибке возвращается FALSE.
В наборе записей возвращаются следующие поля:
TABLE_QUALIFIER;
TABLE_OWNER;
TABLEJAME;
COLUMN_NAME;
KEYJEQ;
PK_NAME.
odbc_foreignkeys
Получение списка внешних ключей
int odbc_foreignkeys (int connection_id, string pk_qualifier, string pk_owner, string pk_table, string fk_qualifier, string fk_owner, string fk_table)
Если pk_table содержит имя таблицы, то функция возвращает набор записей, содержащий первичный ключ этой таблицы и все внешние ключи (foreign keys), которые на него ссылаются.
Если fk_tab!e содержит имя таблицы, то функция возвратцает набор записей, содержащий все внешние ключи этой таблицы и корреспондирующие первичные ключи в других таблицах.
Если и pk_table и fk_table содержат имена таблиц, функция возвращает внешний ключ таблицы fk_table, который указывает на первичный ключ в таблице pk_table.
В возвращаемом наборе записей содержатся следующие поля:
PKTABLE_QUALIFIER;
PKTABLE_OWNER;
PKTABLEJJAME;
PKCOLUMN_NAME;
FKTABLE_QUALIFIER;
FKTABLE_OWNER;
FKTABLE_NAME;
FKCOLUMN_NAME;
KEYJEQ;
UPDATE_RULE;
DELETE_RULE;
FK_NAME; . PKJWME.
odbc_procedures
Получение списка хранимых процедур
int odbc_procedures (int connection_id [, string qualifier [, string owner [, string name]]])
Возвращает список хранимых процедур name в наборе записей, содержащем следующие поля:
PROCEDURE_QUALIFIER;
PROCEDUREJMER;
PROCEDURE_NAME;
NUMJNPUTJ» ARAMS;
NUM_OUTPUT_PARAMS;
- NUM_RESULT_SETS;
REMARKS;
PROCEDURE_TYPE.
Аргументы owner и name могут содержать шаблоны («%» заменяет ноль и более символов, а «_» - один символ).
odbc_procedurecolumns
Получение списка параметров хранимых процедур
int odbc_procedurecolumns (int connection_id [, string qualifier [, string owner [, string proc [, string column>)
Возвращает список хранимых процедур (с их входными и выходными параметрами и описанием возвращаемых ими полей) в наборе записей, содержащем следующие поля:
PROCEDURE_QUALIFIER;
PROCEDURE J1WNER;
PROCEDUREJAME;
COLUMN_NAME;
COLUMN_TYPE;
DATATYPE;
TYPEJAME;
PRECISION;
LENGTH;
SCALE;
RADIX;
NULLABLt;
REMARKS.
Записи сортируются по полям PROCEDURE_QUALIFIER, PROCEDURE_OWNER, PROCEDURE_NAME и COLUMNJYPE.
Аргументы owner, ргос и column могут содержать шаблоны («%» заменяет ноль и более символов, а «_» - один символ).
odbc_specialcolumns
Получение списка специальных полей
int odbc_specialcolumns (int connectionjd, int type. string qualifier, string owner, string table, int scope, int nullable)
Если в аргументе type указано значение SQL_BEST_ROWID, возвращаются поля, уникально идентифицирующие каждую запись в таблице.
Если в аргументе type указано значение SQLJ!OWVER, возвращаются оптимальные ноля, извлекая значения которых, можно уникально идентифицировать любую запись указанной таблицы (вне зависимости от изменений, производимых в таблице).
Поля возвращаются в наборе записей (сортируемом по полю SCOPE), содержащем следующие ноля:
SCOPE;
COLUMN_NAME;
DATAJYPE;
TYPE_NAME;
PRECISION;
LENGTH;
SCALE;
PSEUDO_COLUMN.