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

Чтобы использовать массивы параметров, приложение вызывает SQLSetStmtAttr с аргументом атрибута SQL_ATTR_PARAMSET_SIZE, чтобы указать количество наборов параметров. Он вызывает SQLSetStmtAttr с аргументом Attribute, равным SQL_ATTR_PARAMS_PROCESSED_PTR, чтобы указать адрес переменной, в которую драйвер может вернуть количество обработанных наборов параметров, включая наборы, содержащие ошибки. Он вызывает SQLSetStmtAttr с аргументом Attribute, имеющим значение 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. Возможность использования массивов параметров с другими типами операторов зависит от конкретного источника данных, особенно потому, что использование параметров в таких операторах также зависит от источника данных и не соответствует грамматике SQL ODBC.

Массив, на который указывает атрибут инструкции 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_ATTR_PARAM_STATUS_PTR, устанавливается в SQL_PARAM_ERROR, а вызов SQLExecute, SQLExecDirect, SQLParamData или SQLPutData возвращает SQL_ERROR. Содержимое этого буфера не определено, если sqlExecute, SQLExecDirect или SQLParamData возвращают SQL_STILL_EXECUTING.

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

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