Использование массивов параметров

Чтобы использовать массивы параметров, приложение вызывает SQLSetStmtAttr с аргументом атрибута SQL_ATTR_PARAMSET_SIZE, чтобы указать количество наборов параметров. Он вызывает SQLSetStmtAttr с аргументом атрибута SQL_ATTR_PARAMS_PROCESSED_PTR, чтобы указать адрес переменной, в которой драйвер может возвращать количество обработанных параметров, включая наборы ошибок. Он вызывает SQLSetStmtAttr с аргументом атрибута SQL_ATTR_PARAM_STATUS_PTR указывать на массив, в котором возвращаются сведения о состоянии для каждой строки значений параметров. Драйвер сохраняет эти адреса в структуре, которая поддерживается для инструкции.

Примечание.

В ODBC 2.x, SQLParamOptions был вызван для указания нескольких значений параметра. В ODBC 3.x, вызов SQLParamOptions был заменен вызовом SQLSetStmtAttr , чтобы задать атрибуты SQL_ATTR_PARAMSET_SIZE и SQL_ATTR_PARAMS_PROCESSED_ARRAY.

Перед выполнением инструкции приложение задает значение каждого элемента каждого связанного массива. При выполнении инструкции драйвер использует сведения, сохраненные для получения значений параметров и отправки их в источник данных; Если это возможно, драйвер должен отправлять эти значения в виде массивов. Хотя использование массивов параметров лучше всего реализовано путем выполнения инструкции SQL со всеми параметрами в массиве с одним вызовом источника данных, эта возможность недоступна в DBMSs сегодня. Однако драйверы могут имитировать его, выполняя инструкцию SQL несколько раз, каждый из которых имеет один набор параметров.

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

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

• Проверьте поддержку массивов параметров во время выполнения. Драйвер поддерживает массивы параметров, если можно задать атрибут оператора SQL_ATTR_PARAMSET_SIZE значением больше 1. Универсальные приложения и вертикальные приложения обычно проверка для поддержки массивов параметров во время выполнения.

Доступность счетчиков строк и результирующих наборов в параметризованном выполнении можно определить путем вызова SQLGetInfo с параметрами SQL_PARAM_ARRAY_ROW_COUNTS и SQL_PARAM_ARRAY_SELECTS. Для инструкций INSERT, UPDATE и DELETE параметр SQL_PARAM_ARRAY_ROW_COUNTS указывает, доступны ли отдельные счетчики строк (по одному для каждого набора параметров) или количество строк свернуты в одну (SQL_PARC_BATCH SQL_PARC_NO_BATCH). Для инструкций SELECT параметр SQL_PARAM_ARRAY_SELECTS указывает, доступен ли результирующий набор для каждого набора параметров (SQL_PAS_BATCH) или доступен ли только один результирующий набор (SQL_PAS_NO_BATCH). Если драйвер не разрешает выполнение инструкций создания результирующих наборов с массивом параметров, SQL_PARAM_ARRAY_SELECTS возвращает SQL_PAS_NO_SELECT. Это источник данных, зависящий от того, можно ли использовать массивы параметров с другими типами инструкций, особенно поскольку использование параметров в этих инструкциях будет конкретным источником данных и не будет соответствовать грамматике ODBC SQL.

Массив, на который указывает атрибут оператора SQL_ATTR_PARAM_OPERATION_PTR, можно использовать для пропуска строк параметров. Если для элемента массива задано значение SQL_PARAM_IGNORE, набор параметров, соответствующих этому элементу, исключается из вызова SQLExecute или SQLExecDirect . Массив, на который указывает атрибут SQL_ATTR_PARAM_OPERATION_PTR, выделяется и заполняется приложением и считывается драйвером. Если в качестве входных параметров используются строки, значения массива состояния строки можно использовать в массиве операций параметров.

Обработка ошибок

Если при выполнении инструкции возникает ошибка, функция выполнения возвращает ошибку и задает переменную номера строки в число строки, содержащей ошибку. Это источник данных, независимо от того, выполняются ли все строки, кроме набора ошибок, или все строки до (но не после) выполняется набор ошибок. Так как он обрабатывает наборы параметров, драйвер задает буфер, указанный атрибутом инструкции SQL_ATTR_PARAMS_PROCESSED_PTR, в число обрабатываемой строки. Если все наборы, кроме набора ошибок, выполняются, драйвер устанавливает этот буфер на SQL_ATTR_PARAMSET_SIZE после обработки всех строк.

Если атрибут инструкции SQL_ATTR_PARAM_STATUS_PTR задан, SQLExecute или SQLExecDirect возвращает массив состояния параметров, который предоставляет состояние каждого набора параметров. Массив состояния параметров выделяется приложением и заполняется драйвером. Его элементы указывают, успешно ли выполнена инструкция SQL для строки параметров или произошла ли ошибка при обработке набора параметров. Если произошла ошибка, драйвер задает соответствующее значение в массиве состояния параметров SQL_PARAM_ERROR и возвращает SQL_SUCCESS_WITH_INFO. Приложение может проверка массив состояния, чтобы определить, какие строки были обработаны. Используя номер строки, приложение часто может исправить ошибку и возобновить обработку.

Как используется массив состояния параметров, определяется параметрами SQL_PARAM_ARRAY_ROW_COUNTS и SQL_PARAM_ARRAY_SELECTS, возвращаемым вызовом SQLGetInfo. Для инструкций INSERT, UPDATE и DELETE массив состояния параметров заполняется сведениями о состоянии, если SQL_PARC_BATCH возвращается для SQL_PARAM_ARRAY_ROW_COUNTS, но не если возвращается SQL_PARC_NO_BATCH. Для инструкций SELECT массив состояния параметра заполняется, если SQL_PAS_BATCH возвращается для SQL_PARAM_ARRAY_SELECT, но не возвращается SQL_PAS_NO_BATCH или SQL_PAS_NO_SELECT.

Параметры выполнения данных

Если любое из значений массива длины или индикатора SQL_DATA_AT_EXEC или результат макроса SQL_LEN_DATA_AT_EXEC(длина), данные для этих значений отправляются в SQLPutData обычным образом. Следующие аспекты этого процесса имеют специальный комментарий, потому что они не являются легко очевидными:

• Когда драйвер возвращает SQL_NEED_DATA, он должен задать адрес переменной номера строки в строке, для которой требуется данные. Как и в случае с одним значением, приложение не может делать никаких предположений о порядке, в котором драйвер запрашивает значения параметров в одном наборе параметров. Если ошибка возникает в выполнении параметра data-at-execution, буфер, заданный атрибутом инструкции SQL_ATTR_PARAMS_PROCESSED_PTR, имеет значение SQL_PARAM_ERROR, состояние строки в массиве состояния строки, указанной атрибутом инструкции SQL_ATTR_PARAM_STATUS_PTR, имеет значение SQL_PARAM_ERROR. и вызов SQLExecute, SQLExecDirect, SQLParamData или SQLPutData возвращает SQL_ERROR. Содержимое этого буфера не определено, если sqlExecute, SQLExecDirect или SQLParamData возвращают SQL_STILL_EXECUTING.

• Поскольку драйвер не интерпретирует значение в аргументе ParameterValuePtr sqlBindParameter для параметров выполнения данных, если приложение предоставляет указатель на массив, SQLParamData не извлекает и возвращает элемент этого массива приложению. Вместо этого он возвращает скалярное значение, предоставленное приложением. Это означает, что значение, возвращаемое SQLParamData , недостаточно для указания параметра, для которого приложение должно отправлять данные; приложение также должно учитывать текущий номер строки.

  Если только некоторые элементы массива параметров являются параметрами данных при выполнении, приложение должно передать адрес массива в ParameterValuePtr , который содержит элементы для всех параметров. Этот массив интерпретируется обычно для параметров, которые не являются параметрами данных при выполнении. Для параметров выполнения данных значение , которое SQLParamData предоставляет приложению, которое обычно можно использовать для идентификации данных, запрашиваемых драйвером в этом случае, всегда является адресом массива.