Разработка прикладных программ: Интерфейс уровня вызовов (CLI)

Изменение диагностической таблицы для функции SQLDescribeParam (CLI)

Функция SQLDescribeParam() возвращает описание маркера параметра, связанного с подготовленным оператором SQL.

В диагностическую таблицу добавлено SQLSTATE HYC00.

Асинхронное выполнение интерфейса уровня вызовов

Интерфейс уровня вызовов DB2 (DB2 CLI) может запустить поднабор функций асинхронно. |Драйвер DB2 CLI возвращает управление программе после вызова функции, но до завершения выполнения функции. При каждом вызове функция возвращает значение SQL_STILL_EXECUTING, |пока ее выполнение не будет завершено, после чего она возвратит другое значение, например, SQL_SUCCESS.

Асинхронное выполнение имеет смысл только в однопоточных операционных системах. Программы, запускаемые в многопоточных операционных системах, должны выполнять функции в отдельных потоках. Асинхронное выполнение возможно для функций, которые отправляют на сервер обычные требования и ожидают после этого ответа. Выполнение функций в асинхронном режиме благодаря возврату управления программе позволяет избежать ожидания. Программа после этого может выполнять другие задачи или |возвратить управление операционной системе и при помощи прерывания периодически опрашивать функцию, |пока не будет возвращен код возврата, отличный от SQL_STILL_EXECUTING.

Поддержка асинхронного выполнения CLI включена в DB2 Universal Database (UDB), начиная с Версии |8.2 FixPak 1 (эквивалентна Версии 8.1 FixPak 8). Документацию по этой возможности смотрите |в Информационном центре DB2 UDB Версии 7 на странице |http://publib.boulder.ibm.com/infocenter/db2v7luw/index.jsp. Вся информация в документации для Версии 7 применима к версии 8.2 FixPak 1 (эквивалентна Версии 8.1 FixPak 8) и новее. В Информационном центре DB2 Версии 8 документации об этой возможности нет.

Атрибут соединения SQL_ATTR_PING_DB

Функция SQLBindParameter (CLI)

В документации по функции SQLBindParameter описание в разделе Входной параметр неправильно. Вот правильное описание:

|

Входной параметр

|

Значение ColumnSize 0 означает, что DB2 CLI будет использовать |для типа SQL, заданного в качестве размера столбца или параметра хранимой процедуры, максимальную длину. DB2 CLI будет выполнять все необходимые преобразования, используя этот размер. |

|

Функция SQLMoreResults (CLI)

В документации для функции SQLMoreResults атрибут оператора SQL_ATTR_ROW_ARRAY_SIZE назван неверно. Правильный атрибут оператора - SQL_ATTR_PARAMSET_SIZE. Раздел Использование следует читать так:

Эта функция используется для возврата набора нескольких результатов последовательным методом при выполнении:

|
• Параметризированного запроса с массивом значений входных параметров, заданных при |помощи атрибута оператора SQL_ATTR_PARAMSET_SIZE и SQLBindParameter()

Дополнительные атрибуты среды

Кроме существующих атрибутов соединения CLI, в качестве атрибутов среды CLI поддерживаются также следующие атрибуты:

• SQL_ATTR_INFO_ACCTSTR
• SQL_ATTR_INFO_APPLNAME
• SQL_ATTR_INFO_USERID
• SQL_ATTR_INFO_WRKSTNNAME

Информацию об этих атрибутах смотрите в документации по атрибутам соединения CLI в Информационном центре DB2 или в справочном руководстве CLI Guide and Reference Volume 2.

Требования для динамических указателей с прокруткой

Для выполнения операций изменения и удаления строк в наборах результатов динамических указателей с прокруткой в оператор UPDATE или DELETE должны входить все столбцы хотя бы одного ключа уникальности базовой таблицы. Это может быть первичный ключ или любой другой ключ уникальности.

Ключевое слово конфигурации CLI/ODBC RetCatalogAsCurrServer

|

Описание ключевого слова:

|

Функции каталогизации возвращают для столбцов каталога вместо пустого значения значение CURRENT SERVER. |

|

Синтаксис ключевого слова db2cli.ini:

|

RetCatalogAsCurrServer= 0 | 1 |

|

Значение по умолчанию:

|

Если СУБД назначения возвращает для столбцов каталога пустое значение, значение CURRENT SERVER не подставляется. |

|

Замечания по использованию:

|

Если функции каталогизации для СУБД назначения возвращают для столбцов каталога пустое значение, |задание для RetCatalogAsCurrServer значения 1 приводит к тому, что СУБД возвращает не пустое значение, |а значение CURRENT SERVER. |

|
• 0 = Функции каталогизации возвращают для столбцов каталога пустое значение (по умолчанию).
|
• 1 = Функции каталогизации возвращают для столбцов каталога вместо пустого значения значение CURRENT SERVER.

|

Например, функция каталогизации SQLTables() возвращает набор результатов |с пустыми значениями в столбце TABLE_CAT. Задание для RetCatalogAsCurrServer значения 1 приведет |к тому, что СУБД возвратит в столбце TABLE_CAT значение CURRENT SERVER.

|

| |

Прим.:

|

Это ключевое слово поддерживается DB2 |UDB для Linux, UNIX^(R) и Windows^(R) Версии 8.2 FixPak 3 (эквивалентна Версии 8.1 FixPak 10) |и новее.

|

|

Ключевое слово конфигурации CLI/ODBC ReceiveTimeout

Описание ключевого слова:

Задает срок ожидания ответа от сервера в секундах в установленном соединении перед прекращением попытки и генерацией ошибки истечения срока ожидания связи.

Синтаксис ключевого слова db2cli.ini:

ReceiveTimeout = 0 | 1 | 2 | ... | 32767

Значение по умолчанию:

Время ожидания клиентом ответа от сервера в установленном соединении не ограничено.

Эквивалентный атрибут оператора:

SQL_ATTR_RECEIVE_TIMEOUT

Замечания по использованию:

Значение по умолчанию 0 указывает, что клиент ожидает ответа неограниченно долго. Срок ожидания ответа не влияет на процесс установления соединения; он поддерживается только для TCP/IP и игнорируется для всех других протоколов.

Атрибут оператора SQL_ATTR_RECEIVE_TIMEOUT

SQL_ATTR_RECEIVE_TIMEOUT (DB2 CLI v8)

32-битное целое число, задающее срок ожидания ответа от сервера в секундах в установленном соединении перед прекращением попытки и генерацией ошибки истечения срока ожидания связи. Значение по умолчанию 0 указывает, что клиент ожидает ответа неограниченно долго. Срок ожидания ответа не влияет на процесс установления соединения; он поддерживается только для TCP/IP и игнорируется для всех других протоколов. Поддерживаемые значения - целые числа от 0 до 32767.

Ключевое слово конфигурации CLI/ODBC Reopt

Описание ключевого слова:

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

Синтаксис ключевого слова db2cli.ini:

Reopt = 2 | 3 | 4

Значение по умолчанию:

Во время выполнения запроса его оптимизация не производится. Для специальных регистров и маркеров параметров используются выбранные компилятором оценочные значения по умолчанию.

Эквивалентный атрибут оператора:

SQL_ATTR_REOPT

Замечания по использованию:

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

• 2 = SQL_REOPT_NONE. Это значение по умолчанию. Во время выполнения запроса его оптимизация не производится. Для специальных регистров и маркеров параметров используются выбранные компилятором оценочные значения по умолчанию. Для выполнения динамических операторов SQL используется набор пакетов по умолчанию "NULLID".
• 3 = SQL_REOPT_ONCE. Оптимизация запроса во время его выполнения производится однократно - при первом выполнении этого запроса. Используется набор пакетов "NULLIDR1", при связывании которого использована опция REOPT ONCE.
• 4 = SQL_REOPT_ALWAYS. При каждом выполнении запроса производится его оптимизация или повторная оптимизация. Используется набор пакетов "NULLIDRA", при связывании которого использована опция REOPT ALWAYS.

"NULLIDR1" и "NULLIDRA" - зарезервированные имена наборов пакетов; когда они используются, неявно применяются опции REOPT ONCE и REOPT ALWAYS, соответственно. Эти наборы пакетов нужно явно создать следующими командами:

db2 bind db2clipk.bnd collection NULLIDR1
db2 bind db2clipk.bnd collection NULLIDRA

Если заданы оба ключевых слова Reopt и CurrentPackageSet, приоритет имеет CurrentPackageSet.

Атрибут оператора SQL_ATTR_REOPT

SQL_ATTR_REOPT (DB2 CLI v8)

32-битное целое число, разрешающее оптимизацию запросов для операторов SQL, содержащих специальные регистры или маркеры параметров. При оптимизации для специальных регистров и маркеров параметров вместо выбранных компилятором оценочных значений по умолчанию используются значения, доступные во время выполнения запроса. Допустимые значения этого атрибута:

• 2 = SQL_REOPT_NONE. Это значение по умолчанию. Во время выполнения запроса его оптимизация не производится. Для специальных регистров и маркеров параметров используются выбранные компилятором оценочные значения по умолчанию. Для выполнения динамических операторов SQL используется набор пакетов по умолчанию "NULLID".
• 3 = SQL_REOPT_ONCE. Оптимизация запроса во время его выполнения производится однократно - при первом выполнении этого запроса. Используется набор пакетов "NULLIDR1", при связывании которого использована опция REOPT ONCE.
• 4 = SQL_REOPT_ALWAYS. При каждом выполнении запроса производится его оптимизация или повторная оптимизация. Используется набор пакетов "NULLIDRA", при связывании которого использована опция REOPT ALWAYS.

"NULLIDR1" и "NULLIDRA" - зарезервированные имена наборов пакетов; когда они используются, неявно применяются опции REOPT ONCE и REOPT ALWAYS, соответственно. Эти наборы пакетов нужно явно создать следующими командами:

db2 bind db2clipk.bnd collection NULLIDR1
db2 bind db2clipk.bnd collection NULLIDRA

Атрибуты SQL_ATTR_REOPT и SQL_ATTR_CURRENT_PACKAGE_SET нельзя использовать совместно: если один из них задан, другой недопустим.

Ключевое слово конфигурации CLI/ODBC CurrentPackageSet

Описание ключевого слова:

После каждого соединения передает оператор SET CURRENT PACKAGESET.

Синтаксис ключевого слова db2cli.ini:

CurrentPackageSet = имя_схемы

Значение по умолчанию:

Это условие не добавлено.

Эквивалентный атрибут соединения:

SQL_ATTR_CURRENT_PACKAGE_SET

Замечания по использованию:

Эта опция передает оператор SET CURRENT PACKAGESET SQL со значением CurrentPackageSet после каждого соединения с базой данных. По умолчанию это условие не добавляется.

Оператор SQL SET CURRENT PACKAGESET задает имя схемы (идентификатор собрания), используемое для выборки пакета для последующих операторов SQL.

Прикладные программы CLI/ODBC передают динамические операторы SQL. С помощью этой опции можно управлять привилегиями, используемыми для выполнения этих операторов:

• Выберите схему для использования при выполнении операторов SQL из прикладных программ CLI/ODBC.
• Убедитесь, что у объектов в этой схеме есть необходимые привилегии, и затем выполните соответствующие операции повторного связывания.
• Задайте эту схему в опции CurrentPackageSet.

Теперь операторы SQL из прикладных программ CLI/ODBC будут выполняться под указанной схемой и использовать заданные в ней привилегии.

Следующие имена наборов пакетов зарезервированы: "NULLID", "NULLIDR1", "NULLIDRA".

Если заданы оба ключевых слова Reopt и CurrentPackageSet, приоритет имеет CurrentPackageSet.

Атрибут соединения SQL_ATTR_CURRENT_PACKAGE_SET

SQL_ATTR_CURRENT_PACKAGE_SET (DB2 CLI v5)

Символьная строка с нулевым символом-ограничителем, задающая имя схемы (идентификатор собрания), используемое для выборки пакета для последующих операторов SQL. Если задать этот атрибут, будет передан оператор SQL SET CURRENT PACKAGESET. Если этот атрибут задан перед соединением, оператор SQL SET CURRENT PACKAGESET передается во время соединения.

Прикладные программы CLI/ODBC передают динамические операторы SQL. С помощью этого атрибута соединения можно управлять привилегиями, используемыми для выполнения этих операторов:

• Выберите схему для использования при выполнении операторов SQL из прикладных программ CLI/ODBC.
• Убедитесь, что у объектов в этой схеме есть необходимые привилегии, и затем выполните соответствующие операции повторного связывания. Обычно нужно выполнить связывание пакетов CLI (sqllib/bnd/db2cli.lst) с опцией COLLECTION <id_собрания>. Дополнительную информацию смотрите в описании команды BIND.
• Задайте эту схему в опции CURRENTPACKAGESET.

Теперь операторы SQL из прикладных программ CLI/ODBC будут выполняться под указанной схемой и использовать заданные в ней привилегии.

Другой способ задания имени схемы - задание ключевого слова конфигурации CLI/ODBC CURRENTPACKAGESET.

Следующие имена наборов пакетов зарезервированы: "NULLID", "NULLIDR1", "NULLIDRA".

Атрибуты SQL_ATTR_REOPT и SQL_ATTR_CURRENT_PACKAGE_SET нельзя использовать совместно: если один из них задан, другой недопустим.

Ключевое слово конфигурации CLI/ODBC MapBigintCDefault

Описание ключевого слова:

Задать тип C по умолчанию столбцов BIGINT и маркеров параметров.

Синтаксис ключевого слова db2cli.ini:

MapBigintCDefault = 0 | 1 | 2

Значение по умолчанию:

Тип C по умолчанию для данных BIGINT - SQL_C_BIGINT.

Замечания по использованию:

 

MapBigintCDefault управляет типом C, который используется, когда для столбцов BIGINT и маркеров параметров задается SQL_C_DEFAULT. Это ключевое слово следует использовать преимущественно с прикладными программами Microsoft, такими как Microsoft Access, которые не могут обрабатывать 8-байтные целые числа. MapBigintCDefault задают так:

• 0 - тип C по умолчанию SQL_C_BIGINT
• 1 - тип C по умолчанию SQL_C_CHAR
• 2 - тип C по умолчанию SQL_C_WCHAR

Это ключевое слово влияет на поведение функций CLI, в которых мог быть задан тип C SQL_C_DEFAULT, таких как SQLBindParameter(), SQLBindCol() и SQLGetData().

Ключевое слово конфигурации CLI/ODBC DescribeOutputLevel

Описание ключевого слова:

Задать уровень описательной информации выходного столбца, который был затребован драйвером CLI во время запросов подготовки или описания.

Синтаксис ключевого слова db2cli.ini:

DescribeOutputLevel = 0 | 1 | 2 | 3

Значение по умолчанию:

Требовать описательную информацию, перечисленную в уровне 2 раздела Табл. 25.

Замечания по использованию:

 

Это ключевое слово управляет количеством информации, которое требуется драйверу CLI при требовании подготовки или описания. По умолчанию, когда сервер получает требование описания, в качестве столбцов набора результатов он возвращает информацию, содержащуюся в уровне 2 раздела Табл. 25. Но прикладная программа может и не нуждаться во всей этой информации, а может нуждаться в дополнительной информации.

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

Поддерживаемые значения DescribeOutputLevel:

• 0 - никакая описательная информация программе клиента не возвращается
• 1 - программе клиента возвращается описательная информация, соответствующая уровню 1 (смотрите раздел Табл. 25)
• 2 - (по умолчанию) программе клиента возвращается описательная информация, соответствующая уровню 2 (смотрите раздел Табл. 25)
• 3 - программе клиента возвращается описательная информация, соответствующая уровню 3 (смотрите раздел Табл. 25)

В приведенной ниже таблице перечислены поля описательной информации, возвращаемой сервером в ответ на требование подготовки или описания. Эти поля объединены в уровни; управляет уровнем описательной информации, возвращаемой по требованию драйвера CLI, ключевое слово конфигурации DescribeOutputLevel CLI/ODBC.

SQL_DESC_COUNT
SQL_COLUMN_COUNT
SQL_DESC_TYPE
SQL_DESC_CONCISE_TYPE
SQL_COLUMN_LENGTH
SQL_DESC_OCTET_LENGTH
SQL_DESC_LENGTH
SQL_DESC_PRECISION
SQL_COLUMN_PRECISION
SQL_DESC_SCALE
SQL_COLUMN_SCALE
SQL_DESC_DISPLAY_SIZE
SQL_DESC_NULLABLE
SQL_COLUMN_NULLABLE
SQL_DESC_UNSIGNED
SQL_DESC_SEARCHABLE
SQL_DESC_LITERAL_SUFFIX
SQL_DESC_LITERAL_PREFIX
SQL_DESC_CASE_SENSITIVE
SQL_DESC_FIXED_PREC_SCALE

все поля уровня 1 и:
SQL_DESC_NAME
SQL_DESC_LABEL
SQL_COLUMN_NAME
SQL_DESC_UNNAMED
SQL_DESC_TYPE_NAME
SQL_DESC_DISTINCT_TYPE
SQL_DESC_REFERENCE_TYPE
SQL_DESC_STRUCTURED_TYPE
SQL_DESC_USER_TYPE
SQL_DESC_LOCAL_TYPE_NAME
SQL_DESC_USER_DEFINED_
         TYPE_CODE

все поля уровней 1
и 2 и:
SQL_DESC_BASE_COLUMN_NAME
SQL_DESC_UPDATABLE
SQL_DESC_AUTO_UNIQUE_VALUE
SQL_DESC_SCHEMA_NAME
SQL_DESC_CATALOG_NAME
SQL_DESC_TABLE_NAME
SQL_DESC_BASE_TABLE_NAME