16.3.3. Параметр и результат sql-Функций

SQL-функции принимают параметр nStatementHandle – идентификатор SQL-соединения. Исключение составляют функции SQLSTRINGCONNECT( ) и SQLCONNECT( ), которые этот идентификатор возвращают. Правда, SQLCONNECT( ) также может быть вызвана с параметром nStatementHandle, но об этом см. в описании функции.

Получив идентификатор SQL-соединения, функция в дальнейшем оперирует соединением, с которым этот идентификатор ассоциирован.

Все SQL-функции, принимающие параметр nStatementHandle, кроме функции SQLCONNECT( ), в случае удачного выполнения возвращают число 1; возвращают –1, если возникла ошибка на уровне соединения, и возвращают –2, если произошла ошибка окружения.

Кроме того, функции, выполняемые в асинхронном режиме, возвращают 0, если находятся в процессе получения результата.

Если обнаружена ошибка, то причину ошибки можно проанализировать, употребив функцию AERROR( ).

16.3.4. Выполнение sql-функций в асинхронном режиме

SQL-функции SQLTABLES( ), SQLCOLUMNS( ), SQLMORERESULTS( ) и SQLEXEC( ) могут выполняться как синхронно, так и асинхронно. При асинхронном выполнении функция должна вызываться неоднократно до тех пор, пока она не вернет отличную от нуля величину (1 в случае удачи или –1 или –2 в случае возникновения ошибки). Результат равный нулю означает, что функция все еще выполняется.

По умолчанию соединение функционирует в синхронном режиме. Для переключения в асинхронный режим свойство соединения Asynchronous устанавливается равным .T.

16.3.5. SQL-Функции

Функция

SQLCONNECT([nStatementHandle])

или

SQLCONNECT([cConnectionName | cDataSourceName [, cUserID [, cPassword ]] [, lShared]])

устанавливает SQL-соединение с источником данных. Функция возвращает идентификатор SQL-соединения – положительное значение типа Numeric, если соединение установлено, и –1 – в противном случае.

Замечание. Следует различать идентификатор соединения и возвращаемый функцией SQLCONNECT( ) идентификатор SQL-соединения, посредством которого осуществляется доступ к источнику данных. Все прочие SQL-функции оперируют именно этим идентификатором.

Параметры:

nStatementHandle – обеспечивает создание нового идентификатора SQL-соединения для существующего разделяемого SQL-соединения, представленного nStatementHandle. Новый идентификатор перенимает установки идентификатора nStatementHandle, а не использует заданные по умолчанию. При попытке создать новый идентификатор для неразделяемого соединения VFP генерирует ошибку.

Функция SQLCONNECT(nStatementHandle) может быть также употреблена для получения нового идентификатора SQL-соединения, на основе разделяемого SQL-соединения открытого функцией SQLSTRINGCONNECT( ).

cConnectionName – имя соединения, созданного командой CREATE CONNECTION или проектировщиком соединения. База данных, которой принадлежит соединение cConnectionName, в момент выполнения SQLCONNECT( ) должна быть текущей.

Вызов SQLCONNECT( ) с параметром cConnectionName и без параметра lShared или с lShared равным .F. приведет к созданию неразделяемого соединения.

cDataSourceName – ODBC-имя источника данных.

Источник данных может быть выбран в Select Connection or Data Source-диалоге, который появляется при вызове SQLCONNECT( ) без единого параметра или только с параметром lShared.

cUserID – идентификатор пользователя.

cPassword – пароль пользователя.

lShared – соединение откроется неразделяемым, если параметр равен .F. (по умолчанию), и разделяемым – в противном случае.

Замечание. Необходимо закрыть Login-диалог ODBC, обеспечив тем самым проход SQL через Microsoft Transaction Server. Чтобы это сделать, либо используется вызов

&& nStatementHandle – идентификатор SQL-соединения, выработанный SQLCONNECT( )

SQLSetProp(nStatementHandle, 'DispLogin', 3)

либо употребляется проектировщик соединения.

Пример. Создаются 3 идентификатора SQL-соединений, ассоциированных с одним и тем же ODBC-источником данных – BookSale.

close databases

open database d:\HomeLibrary\HomeLibrary

&& Разделяемое SQL-соединение на основе именованного соединения BookSale

nStHandle1 = SQLConnect('BookSale', .T.)

&& Разделяемое SQL-соединение; указываем ODBC-имя источника данных

nStHandle2 = SQLConnect('BookSaleDataBase', 'nick', 'name', .T.)

&& Новый идентификатор на основе существующего SQL-соединения && с идентификатором nStHandle2

nStHandle3 = SQLConnect(nStHandle2)

? nStHandle1, nStHandle2, nStHandle3

&& Разрываем SQL-соединения

SQLDisconnect(nStHandle1)

SQLDisconnect(nStHandle2)

SQLDisconnect(nStHandle3)

Возможный вывод:

1 2 3

Функция

SQLSTRINGCONNECT([lShared] | [cConnectString [, lShared]])

устанавливает SQL-соединение с источником данных, используя строку соединения. Возвращает, как и SQLCONNECT( ), идентификатор SQL-соединения или –1, если соединение не установлено.

Параметры:

lShared – соединение откроется неразделяемым, если параметр равен .F. (по умолчанию), и разделяемым – в противном случае.

cConnectString – строка соединения источника данных, требуемая при работе с некоторыми ODBC-драйверами.

Замечание. Источник данных можно выбрать в диалоге "Выбор источника данных", который откроется, если вызвать SQLSTRINGCONNECT( ) без cConnectString, например:

nStHandle = SQLStringConnect(.T.)

или

nStHandle = SQLStringConnect("", .T.)

Пример. Устанавливается SQL-соединение с источником данных BookSaleDataBase.

&& Пробелы между именами и знаками должны отсутствовать

nStHandle = SQLStringConnect('dsn=BookSaleDataBase;uid=nick;pwd=name')

или, когда идентификатор и пароль пользователя хранят переменные:

myUid = 'nick'

myPass = 'name'

nStHandle = SQLStringConnect('dsn=BookSaleDataBase;uid=<myUid>;pwd=<myPass>')

if nStHandle > 0 then

MessageBox('SQL-соединение создано!')

&& Разрываем SQL-соединение

SQLDisconnect(nStHandle)

else

MessageBox('Не удалось создать SQL-соединение!')

endif

Пример. Показывает, как использовать SQLSTRINGCONNECT( ) без имени DSN.

lcDSNLess="driver=SQL Server;server=<servername>;uid=<userid>;pwd=<password>"

или

lcDSNLess="driver={SQL Server};server=<servername>;uid=<userid>;pwd=<password>"

или

lcDSNLess="driver={SQL Server};" ;

+ "server=<servername>;" ;

+ "uid=<userid>;" ;

+ "pwd=<password>;" ;

+ "database=PUBS;" ;

+ "wsid=<machine name or userid>;" ;

+ "app=MicroX(R) Sample App"

nStHandle = SQLStringConnect(lcDSNLess)

Замечание. Строка соединения, формируемая проектировщиком соединения при выборе переключателя Connection string и последующем указании в качестве источника данных BookSaleDataBase, может иметь следующий вид:

DSN=BookSaleDataBase;DBQ=C:\AccessData\BookSale.mdb;DefaultDir=C:\AccessData;DriverId=25;FIL=MS Access;MaxBufferSize=4096;PageTimeout=5;PWD=name;UID=admin;

Функция

SQLDISCONNECT(nStatementHandle)

разрывает SQL-соединение, указанное параметром nStatementHandle, с источником данных.

Вызов

SQLDISCONNECT(0) && nStatementHandle = 0

разрывает все активные SQL-соединения.

Если функцию вызвать внутри последовательности функций, работающих в асинхронном режиме, или во время транзакции, то VFP сгенерирует ошибку.

Результат и параметр функции описаны в разд. 16.3.3.

Функция

SQLIDLEDISCONNECT(nStatementHandle)

временно разрывает SQL-соединение. Возвращает 1, если действие выполнено, или –1 – в противном случае. Неудача может возникнуть, например, если соединение занято.

Временно прерванное соединение автоматически восстанавливается, как только возникает необходимость в выполнении операции. ODBC-свойство ODBChstmt равно 0, если идентификатор соединения временно освобожден; свойство ODBChdbc равно 0, если соединение временно прервано. Разделяемое соединение временно прерывается после временного освобождения всех его идентификаторов.

Функция

SQLSETPROP(nStatementHandle, cSetting [, eExpression])

устанавливает свойство, указанное параметром cSetting, активного соединения, заданного параметром nStatementHandle. Если в качестве nStatementHandle передан 0, то SQLSETPROP( ) установит свойство на уровне окружения соединения.

Результат функции и параметр nStatementHandle описаны в разд. 16.3.3.

Параметр:

cSetting – строка с именем устанавливаемого свойства. Может принимать приведенные в табл. 16.7 значения (часть свойств описана в табл. 14.15).

Таблица 16.7