Отправка длинных данных

DBMS определяют длинные данные как любые символы или двоичные данные с определенным размером, например 254 символа. Возможно, невозможно сохранить весь элемент длинных данных в памяти, например, когда элемент представляет длинный текстовый документ или растровое изображение. Так как эти данные не могут храниться в одном буфере, источник данных отправляет его драйверу в части с SQLPutData при выполнении инструкции. Параметры, для которых данные отправляются во время выполнения, называются параметрами данных во время выполнения.

Замечание

Приложение может отправлять любые типы данных во время выполнения с помощью SQLPutData, хотя только символьные и двоичные данные могут отправляться в частях. Однако если данные достаточно малы для размещения в одном буфере, обычно нет причин использовать SQLPutData. Гораздо проще привязать буфер и позволить драйверу получать данные из буфера.

Чтобы отправить данные во время выполнения, приложение выполняет следующие действия:

1. Передает 32-разрядное значение, которое определяет параметр в аргументе ParameterValuePtr в SQLBindParameter , а не передает адрес буфера. Это значение не анализируется драйвером. Оно будет возвращено приложению позже, поэтому оно должно означать что-то для приложения. Например, это может быть число параметра или дескриптор файла, содержащего данные.

2. Передает адрес буфера длины или индикатора в аргументе StrLen_or_IndPtrSQLBindParameter.

3. Сохраняет SQL_DATA_AT_EXEC или результат макроса SQL_LEN_DATA_AT_EXEC(длина) в буфере длины или индикатора. Оба этих значения указывают драйверу, что данные для параметра будут отправлены с помощью SQLPutData. SQL_LEN_DATA_AT_EXEC(длина) используется при отправке длинных данных в источник данных, который должен знать, сколько байтов длинных данных будет отправлено таким образом, чтобы он смог предварительно выделить пространство. Чтобы определить, требуется ли для источника данных это значение, приложение вызывает SQLGetInfo с параметром SQL_NEED_LONG_DATA_LEN. Все драйверы должны поддерживать этот макрос; Если источник данных не требует длины байтов, драйвер может игнорировать его.

4. Вызывает SQLExecute или SQLExecDirect. Драйвер обнаруживает, что буфер длины или индикатора содержит значение SQL_DATA_AT_EXEC или результат макроса SQL_LEN_DATA_AT_EXEC(длина) и возвращает SQL_NEED_DATA в качестве возвращаемого значения функции.

5. Вызывает SQLParamData в ответ на возвращаемое значение SQL_NEED_DATA. Если требуется отправить длинные данные, SQLParamData возвращает SQL_NEED_DATA. В буфере, на который указывает аргумент ValuePtrPtr, драйвер возвращает значение, идентифицирующее параметр выполнения данных. Если существует более одного параметра данных, определяемого во время выполнения, приложение должно использовать это значение для решения, по какому именно параметру отправлять данные; драйверу не требуется запрашивать данные для таких параметров в каком-либо определенном порядке.

6. Вызывает SQLPutData для отправки данных параметров драйверу. Если данные параметра не помещаются в один буфер, как это часто бывает с длинными данными, приложение неоднократно вызывает SQLPutData для отправки данных по частям, а задача драйвера и источника данных — собрать данные заново. Если приложение передает данные строки, завершаемые значением NULL, драйвер или источник данных должны удалить символ завершения null в процессе повторной сборки.

7. Вызывает SQLParamData еще раз, чтобы указать, что он отправил все данные для параметра. Если существуют параметры, для которых данные не были отправлены, драйвер возвращает SQL_NEED_DATA и значение, определяющее следующий параметр; приложение возвращается на шаг 6. Если данные были отправлены для всех параметров выполнения данных, инструкция выполняется. SQLParamData возвращает SQL_SUCCESS или SQL_SUCCESS_WITH_INFO и может возвращать любое возвращаемое значение или диагностику, которые sqlExecute или SQLExecDirect могут возвращать.

После того как SQLExecute или SQLExecDirect возвращает SQL_NEED_DATA и до того, как данные были полностью отправлены для последнего параметра данных при выполнении, инструкция находится в состоянии "Необходимые данные". Хотя инструкция находится в состоянии "Необходимые данные", приложение может вызывать только SQLPutData, SQLParamData, SQLCancel, SQLGetDiagField или SQLGetDiagRec; все остальные функции возвращают SQLSTATE HY010 (ошибка последовательности функций). Вызов SQLCancel отменяет выполнение инструкции и возвращает его в предыдущее состояние. Дополнительные сведения см. в приложении B: таблицы перехода состояния ODBC.

Пример отправки данных во время выполнения см. в описании функции SQLPutData .