Соединение с источником данных с помощью базовых функций:
RETCODE SQLConnect (HDBC hdbc, // идентификатор соединения
UCHAR FAR * szDSN, // имя источника данных
SWORD sbDSN, // длина имени источника
// м.быь равна SQL_NTS, если
// строка заканчивается нулем
UCHAR FAR *szUID, // идентификатор пользователя
SWORD sbUID, // его длина (SQL_NTS)
UCHAR FAR * szAuthStr, // пароль
SWORD cbAuthStr); // его длина (SQL_NTS)
Для одноранговых СУБД, таких, как dBase или Btrieve для установки соединения требуется только идентификатор соединения и имя источника данных, остальные параметры - ноль или пустая строка.
тсоединение от источника данных:
SQLDisconnect(HDBC hdbc);
Получить имена потенциальных источников данных:
RETCODE SQLDataSources(
HENV henv, // идентификатор окружения
UWORD fDirection, // принимает значения SQL_FETCH_FIRST или
// SQL_FETCH_NEXT. Определяет выбрать первый
// или следующий источник
UCHAR FAR *szDSN, // указатель на имя источника
SWORD cbSNMax, // Максимальная длина имени источника
// (не требуется более SQL_MAX_DSN_LENGTH+1)
SWORD FAR *pcbDSN, // число байт возвращенного имени источника
// (не считая хвостового нуля)
UCHAR FAR *szDescription, // Указатель на полученное описание
SWORD cbDescriptionMax, // число байт данное под описание
SWORD FAR *pcbDescription); // число байт полученного описания
Функция возвращает источники поочередно по одному за обращение. Окончание определяется по коду возврата SQL_NO_DATA_FOUND.
Многие СУБД кроме имени пользователя и пароля имеют и другие атрибуты соединения. Эти атрибуты являются разными для разных СУБД, и, поэтому ODBC должна выполнить присоединение к источнику другим способом.
RETCODE SQLDriverConnect(
HDBC hdbc, // идентификатор соединения
HWND hwnd, // идентификатор окна. Программа может передать
// идентификатор родительского окна или 0, если
// SQLDriverConnect не имеет диалога
UCHAR FAR *szConStrIn, // строка полного соединения, строка
// частичного соединения или пустая строка
SWORD cbConStrIn, // длина szConStrIn
UCHAR FAR *szConStrOut, // указатель на строку законченного
// соединения (не < 255 байт)
SWORD cbConStrOutMax, // максимальная длина szConStrOut
SWORD FAR *pcbConStrOut, // действительная длина строки завер-
// шенного соединения
fDriverCompletion); // Входной флаг, указывающий должен ли
// Менеджер драйверов или драйвер вести диалог для
Строка соединения представляет собой последовательность пар вида
<имя атрибута>=<значение атрибута>, разделяемых точкой с запятой.
Например:
DSN=ACCOUNTING;UID=BILLM;PWD=LANDSHARK;SN=ACCSERV
где DSN - имя источника данных
UID - имя пользователя
PWD - пароль
SN - имя сервера
Строка соединения полностью или частично заполняется приложением и может содержать атрибуты, специфические для конкретного драйвера. Недостающие данные в строке соединения должна заполнить функция SQLDriverConnect. Если szConStrIn не содержит DSN или DRIVER, то менеджер драйверов выполняет описанные ниже действия:
SQL_DRIVER_PROMPT:
открывает окно диалога "Источники данных", которое содержит все имена источников данных. Пользователь должен выбрать источник данных.
SQL_DRIVER_COMPLETE или SQL_DRIVER_COMPLETE_REQUIRED:
если не задан DSN, то также как в случае SQL_DRIVER_PROMPT, в противном случае используется указанный DSN.
Менеджер драйверов не выполняет приглашения на ввод, если задано SQL_DRIVER_NOPROMPT или в строке соединения имеется ключевое слово DRIVER. Если строка содержит DSN, то загружается соответствующий драйвер, определенный в ODBC.INI. Если определено DRIVER, а не DSN, то загружается этот драйвер. Если не определено ни то ни другое, то загружается драйвер по умолчанию.
Как только менеджер драйверов определит какой драйвер надо загружать, он передает строку соединения функции SQLDriverConnect этого драйвера. Подобно менеджеру драйверов, драйвер выполняет различные действия в зависимости от значения fDriverCompletion и содержимого строки соединения. Драйвер не может загрузить какую-либо информацию для источника данных, если задан атрибут DRIVER.
Прикладной программе может потребоваться выполнить несколькопоследовательных вызовов SQLFreeStmt. Например, для того, чтобы освободить параметр и отбросить его ожидаемое результирующее множество, SQLFreeStmt нужно вызвать дважды: для первого вызова fOption=SQL_RESET_PARAMS, для второго - SQL_CLOSE.
1.1.4.2.SQLExecDirect
Функция подготавливает и выполняет SQL-оператор:
RETCODE SQLExecDirect(
HSTMT hstmt, // идентификатор оператора
UCHAR FAR * szSqlStr, // SQL-оператор
SDWORD cbSqlStr); // его длина (м.быть SQL_NTS)
);
Данную функцию используют, если есть уверенность в том, что SQL оператор должен быть выполнен однократно, то есть что он больше не понадобится.
1.1.4.3.SQLPrepare и SqlExecute
Функция SQLPrepare подготавливает выполнение SQL оператора, а функция SQLExecute выполняет подготовленный оператор. Этой парой целесообразно пользоваться в случае когда SQL - оператор используется неоднократно.
Прототипы этих функций:
RETCODE SQLPrepare(
HSTMT hstmt, // идентификатор оператора
UCHAR FAR * szSqlStr, // SQL - оператор
SDWORD cbSqlStr // длина SQL _ оператора
);
RETCODE SQLExecute(HSTMT hstmt);
1.1.4.4.SQLBindParameter
SQL - оператор может иметь параметры, связывающие его с переменными прикладной программы. Места параметров (маркеры) определяются в SQL-операторах с помощью символа "?".
Например:
SELECT * FROM S WHERE np=?
или
INSERT INTO EMP (empid, firstname) VALUES (?,?)
Связывание маркеров и параметров выполняется функциейSQLBindParameter.
Прототип:
RETCODE SQLBindParameter(
HSTMT hstmt, // идентификатор оператора
UWORD ipar, // номер параметра, упорядоченный слева направо
// отсчет от 1
SWORD fParamType, // тип параметра, который может принимать
// одно из значений: SQL_PARAM_INPUT,
// SQL_PARAM_INPUT_OUTPUT, SQL_PARAM_OUTPUT
SWORD fCtype, // C-тип данных параметра, который может принимать
// значения: SQL_C_BINARY, SQL_C_BIT, SQL_C_СHAR,
// SQL_C_DATE, SQL_C_DEFAULT, SQL_C_DOUBLE,
// SQL_C_FLOAT, SQL_C_SLONG, SQL_C_SSHORT,
// SQLC_STINYINT, SQL_C_TIME, SQL_C_TIMESTAMP,
// SQL_C_ULONG, SQL_C_USHORT, SQL_C_UTINY_INT,
// Отметим, что SQL_C_DEFAULT означает, что значение
// параметра было передано из С-типа данных по
// умолчанию в SQL-тип данных, определенный fSqlType.
SWORD fSqlType, // SQL-тип данных параметра, который может быть
// один из следующих: SQL_BIGINT, SQL_BINARY,
// SQL_BIT, SQL_CHAR, SQL_DATE, SQL_DECIMAL,
// SQL_DOUBLE, SQL_FLOAT, SQL_INTEGER,
// SQL_LONGVARBINARY, SQL_NUMERIC, SQL_REAL,
// SQL_SMALLINT, SQL_TIME, SQL_TIMESTAMP,
// SQL_TINYINT, SQL_VARBINARY, SQL_VARCHAR
UDWORD cbColDef, // число байт, которое будет послано в параметр
// для типов SQL_LONGVARBINARY или SQL_LONGVARCHAR
// когда приложение на ODBC 2.0 вызывает драйвер
// ODBC 1.0 и данные будут пересылаться с помощью
// SQLPutData.
SWORD ibScale, // масштаб столбца или выражения, соответствующего
// маркеру параметра.
PTR rgbValue, // указатель буфера данных для параметра, который
// при вызове SQLExecute или SQLExecDirect
// содержит действительное значение параметра
SDWORD cbValueMax, // Максимальная длина параметра.
// Используется только тогда, когда тип
// SQL_LONGVARBINARY или SQL_LONGVARCHAR
SDWORD FAR * pcbValue // Указатель на действительную длину
// параметра для SQL_LONGVARCHAR и
// SQL_LONGVARBINARY или одно из значений:
// SQL_NTS, SQL_NULL_DATA, SQL_DATA_AT_EXEC,
// SQL_DEFAULT_PARAM. Для типов предопределенной
// длины игнорируется.
);
Параметр cbColDef - точность столбца.
Точность числового столбца или параметра это максимальное число цифр, используемых типом данных столбца или параметра. Точность нечислового столбца или параметра это максимальная длина столбца или параметра. Определить максимальную точность, позволяемую для типа данных, можно с помощью функции SQLGetTypeInfo.
Параметр ibscale - масштаб.
Масштаб числового столбца или параметра есть максимальное число цифр справа от десятичной точки. Для числа с плавающей точкой масштаб не определен.
Тип SQL_C_DEFAULT подразумевает C-тип по умолчанию:
Функция SQLParamOption позволяет прикладной программе определить множество значений для набора параметров, которые назначаются с помощью SQLBindParameter. Эта функция особенно полезна, когда нужно выполнить один и тот же SQL-оператор для разных значений параметров.
RETCODE SQLParamOptions(
HSTMT hstmt, // дескриптор оператора
UDWORD crow, // число значений для каждого параметр
// если crow > 1, то rgbValue в SQLBindParameter указывает на массив значений
// параметра, а pcbValue указывает на массив длин.
UDWORD FAR * pirow // указатель на память для хранения текущего
// номера строки. Когда обрабатывается очередное значение параметра, pirow
// устанавливается равным номеру этой строки. Номер строки не будет
// возвращен, если pirow==NULL.Номер начальной строки равен 1. Содержимое
// pirow можно использовать, например, следующим образом: - если возвраща
// ется SQL_NEED_DATA, то можно установить при каком значении параметра
SQLPrepare(hstmt, "INSERT INTO CITIES VALUES (?)", SQL_NTS);
SQLParamOptions(hstmt, 5, &irow);
while (TRUE) {
retcode = SQLExecute(hstmt);
if (retcode != SQL_ERROR) {
break;
}
/* При ошибке, напечатать ее. Если ошибка в 1 строке, откатить транзакцию и выйти. Если ошибка в другой строке, завершить транзакцию, и, несмотря на ощибку перейти к работе со следующим значения параметра */
SQLParamData используется совместно с SQLPutData для определениязначений параметров во время выполнения оператора.
Прототип:
RETCODE SQLParamData(
HSTMT hstmt, // идентификатор оператора
PTR FAR *prgbValue // Указатель области хранения значения
// которое было определено для аргумента rgbValue
// в SQLBindParameter (для значений параметров)
// или адрес буфера rgbValue, определенный в SQLBindCol
// (для значения столбца
);
SQLPutData позволяет прикладной программе передавать данные(символьные, двоичные или специфические) в качестве значения параметра или отдельного столбца во время выполнения оператора.
Прототип:
RETCODE SQLPutData(
HSTMT hstmt, // идентификатор оператора
PTR rgbValue, // Указатель области хранения значений параметра
// или столбца. Данные должны быть представлены
// в формате fCType, определенном функцией
// SQLBindParameter или SQLBindCol
SDWORD cbValue // длина rgbValue. Определяет объем данных,
// которые посылаются при вызове SQLPutData
);
В следующем примере приложение подготавливает SQL оператордля выполнения вставки в таблицу EMPLOYEE. Оператор содержит параметры для полей NAME, ID, PHOTO. Для каждого параметра приложение вызывает SQLBindParameter для определения данных Си и SQL параметра.
Указывается также, что данные для первого и третьегопараметра будут переданы во время исполнения оператора и передаетзначения 1 и 3 для отсроченной выборки данных с помощью SQLParamData. Эти значения идентифицируют параметр, который будет обрабатываться. Приложение вызывает функцию GetNextID, чтобы получить очередной номер служащего. Затем оно вызывает SQLExecute, которое возвратит SQL_NEED_DATA, когда ему потребуются данные для первого и третьего параметров. Приложение вызовет SQLParamData и извлечет значение, которое было туда помещено функцией SQLBindParameter; оно использует это значение, чтобы определить какому параметру послать значение.
Для каждого параметра приложение вызывает InitUserData, чтобы инициировать подпрограмму, возвращающую данные. Затем повторно вызывает GetUserData и SQLPutData для того, чтобы получить и послать значение параметра. В конце концов вызывается SQLParamData, чтобы индицировать, что все данные для параметра посланы и сделать выборку значения для следующего параметра. После того, как данные будут пересланы для всех параметров, SQLParamData вернет SQL_SUCCESS.
Для первого параметра InitUserData ничего не делает, а GetUserData вызывает подпрограмму для ввода имени служащего.
Для третьего параметра InitUserData вызывает подпрограмму для ввода имени файла, содержащего фотографию служащего и открывает этот файл. GetUserData читает по MAX_DATA_LEN байт из этого файла за раз. После того, как весь файл будет прочитан, он закрывается.
Заметим, что некоторые прикладные подпрограммы в тексте опущены.
/* InitUserData. Вызываем GetUserData и SQLPutData неоднократно, */
/* чтобы получить и передать всю информацию о параметре. */
/* Вызываеи SQLParamData, чтобы закончить обработку */
/* текущего параметра и начать обрабатывать следующий параметр. */
while (retcode == SQL_NEED_DATA) {
retcode = SQLParamData(hstmt, &pToken);
if (retcode == SQL_NEED_DATA) {
InitUserData((SWORD)pToken, InitValue);
while (GetUserData(InitValue, (SWORD)pToken, Data, &cbData))
SQLPutData(hstmt, Data, cbData);
}
}
}
//===========================================
VOID InitUserData(SWORD sParam, PTR InitValue) {
UCHAR szPhotoFile[MAX_FILE_NAME_LEN];
switch sParam {
case 3:
/* Запросить у пользователя имя файла, содержащего фото */
PromptPhotoFileName(szPhotoFile);
/* открыть файл
OpenPhotoFile(szPhotoFile, (FILE *)InitValue);
break;
}
}
//=============================================
BOOL GetUserData(PTR InitValue, SWORD sParam,
UCHAR *Data, SWORD *cbData) {
switch sParam {
case 1:
/* Запрос имени служащего */
PromptEmployeeName(Data);
*cbData = SQL_NTS;
return (TRUE);
case 3:
/* GetNextPhotoData считывает следующий кусочек фотографии и */
/* получает число прочитанных байт (до MAX_DATA_LEN). */
Done = GetNextPhotoData((FILE *)InitValue, Data,
MAX_DATA_LEN, &cbData);
if (Done) {
ClosePhotoFile((FILE *)InitValue);
return (TRUE);
}
return (FALSE);
}
return (FALSE);
}
1.1.5. Асинхронное выполнение
Иногда для выполнения SQL-оператора может потребоваться значительное время. Как только такой оператор передается на сервер, то по умолчанию ODBC будет ждать пока не кончится выполнение оператора на сервере. Если пользователь хочет, чтобы его компьютер в это время занялся чем-нибудь полезным, то для этого существует возможность асинхронного выполнения SQL-оператора. Программа сначала должна вызвать SQLSetConnectOption или SQLSetStatementOption и установить fOptionSQL_ASINC_ENABLE в TRUE. Установка опции соединения разрешает асинхронное выполнение всех операторов для этого соединения. Установка опции оператора разрешает асинхронное выполнение только для этого оператора. Далее можно вызвать любую функцию, поддерживающую асинхронное выполнение. Функция будет возвращать SQL_STILL_EXECUTING пока не закончится ее выполнение.
Чтобы выяснить закончилось ли выполнение функции, программа повторно ее вызывает. Если с тем же идентификатором оператора вызывается любая другая функция, кроме SQLCancel, то возвращается SQL_ERROR. Программа может прекратить выполнение функции с помощью SQLCancel.
Прототип SQLSetConnectOption имеет вид:
RETCODE SQLSetConnectOption (
HDBC hdbc, // идентификатор соединения
UWORD fOption, // опция, которую следует установить
UDWORD vParam // Устанавливаемое значение. В зависимости от fOption
// может быть 32-битовым целым или указателем на
// строку, заканчивающуюся нулем.
);
Некоторые возможные значения fOption и соответствующие им значения vParam приведены ниже.
fOption=SQL_ASYNC_ENABLE. vParam может принимать значения SQL_ASYNC_ENABLE_ON и SQL_ASYNC_ENABLE_OFF. Умолчание - SQL_ASYNC_ENABLE_OFF. Если некоторая функция вызвана для асинхронного выполнения, то никакая другая функция, кроме SQLAllocStmt, SQLCancel, или SQLGetFunctions не может быть вызвана для того же оператора или соединения до тех пор, пока асинхронно выполняемая функция не вернет что-то отличное от SQL_STILL_EXECUTING. Если это все же будет сделано, то вызванная функция будет возвращать SQL_ERROR.
Следующие функции могут быть вызваны асинхронно:
SQLColAttributes SQLColumnPrivileges
SQLColumns SQLDescribeCol
SQLDescribeParam SQLExecDirect
SQLExecute SQLExtendedFetch
SQLFetch SQLForeignKeys
SQLGetData SQLGetTypeInfo
SQLMoreResults SQLNumParams
SQLNumResultCols SQLParamData
SQLPrepare SQLPrimaryKeys
SQLProcedureColumns SQLProcedures
SQLPutData SQLSetPos
SQLSpecialColumns SQLStatistics
SQLTablePrivileges SQLTables
fOption=SQL_ACCESS_MODE. vParam может принимать значения SQL_MODE_READ_ONLY и SQL_MODE_READ_WRITE. Первое означает, что оператор не намерен модифицировать данные в базе. Умолчанием является SQL_MODE_READ_WRITE.
FOption=SQL_AUTOCOMMIT. vParam может принимать значения
SQL_AUTOCOMMIT_ON и SQL_AUTOCOMMIT_OFF. В первом случае буферы
сбрасываются немедленно по исполнении оператора.
Другие значения fOption будут рассмотрены в связи с транзакциями.
Функция SQLSetStmtOption имеет такие же параметры.
1.1.6. Скалярные функции
В SQL-операторах могут быть использованы скалярные функции. Форма их включения в SQL-оператор имеет вид
{ fn <имя функции>(аргументы)}, например:
select something, {fn UCASE(fname)} from my_table
Функции делятся на пять групп. Каждая группа имеет fInfoType для функции SQLGetInfo:
Строковые функции SQL_STRING_FUNCTIONS
Числовые функции SQL_NUMERIC_FUNCTIONS
Функции времени и даты SQL_TIMEDATE_FUNCTIONS
Функции преобразования типа SQL_CONVERT_FUNCTIONS
SQLGetInfo возвращает 32-битовую маску, которая перечисляет все поддерживаемые функции.
Системные функцииработают со значениями NULL, а также возвращают информацию о пользователях и базе данных. (не показывает ни одной системной функции )
Функции преобразования типов данных - существует только одна такая функция - CONVERT. Функция CONVERT имеет два параметра: value_exp и data_type. Параметр value_exp может быть строковым или числовым литералом, именем столбца или результатом другой скалярной функции. Data-type - это SQL-тип, в который вы хотите преобразовать value_exp.
Пример преобразовывает номер телефона в символьный вид, после этого он может быть использован в предикате LIKE:
select name, phone from klient where {fn CONVERT(phone, SQL_CHAR)} like ‘33%’
1.1.7. Типы данных: время, дата и временные метки
Несмотря на то, что указанные типы форматируются различно для различных баз данных, escape - фразы ODBC обеспечивают общий формат.
Дата представляется в виде: {d’yyyy-mm-dd’}; время : {t’hh:mm:ss}, а временная метка (timestamp) : {ts’yyyy-mm-dd hh:mm:ss[.f...]}, где f - доли секунд.
Например:
insert into first_table (datecol) values ({d‘1997-11-23’})
select * from another_table where timecol > ({t’11:45:09’})
delete from third_table where tscol < {ts’1996-11-24 11:45:25.67’}
1.1.8. Выборка информации о результате запроса.
1.1.8.1.SQLNumResultCols
Функция возвращает число столбцов запроса. Прототип:
RETCODE SQLNumResultCols(
HSTMT hstmt, // идентификатор оператора
SWORD FAR *pccol // указатель на возвращаемое число столбцов.
);
Функция возвращает 0 для всех операторов, кроме SELECT и вызова процедур.
