Описание

SPI_prepare создаёт и возвращает подготовленное выражение для указанной команды, но не выполняет саму команду. В дальнейшем подготовленное выражение можно будет многократно выполнять с помощью SPI_execute_plan.

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

Подготовленную команду можно сделать универсальной, указав параметры ($1, $2, и т. д.) вместо констант, которые использовались бы в обычной команде. Конкретные значения параметров в этом случае указываются при SPI_execute_plan вызывается. Это позволяет использовать подготовленную команду в более широком диапазоне ситуаций, чем это было бы возможно без параметров.

Выражение, возвращаемое функцией SPI_prepare может быть использовано только в текущем вызове функции на языке C, так как SPI_finish освобождает память, выделенную для такого выражения. Но выражение можно сохранить на более долгий срок, используя функции SPI_keepplan или SPI_saveplan.

Аргументы

Возвращаемое значение

SPI_prepare возвращает ненулевой указатель на SPIPlan, представляющий собой непрозрачную структуру, соответствующую подготовленному выражению. В случае ошибки NULL будет возвращено, и SPI_result будет установлено в один из тех же кодов ошибок, которые используются SPI_execute, за исключением того, что устанавливается значение SPI_ERROR_ARGUMENT если command имеет значение NULL, или если nargs меньше 0, или если nargs больше 0 и argtypes имеет значение NULL.

Примечания

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

Хотя основное назначение подготовленного выражения — избежать повторного синтаксического анализа и планирования, Digital Q.DataBase принудительно вызовет повторный анализ и повторное планирование выражения перед его использованием в тех случаях, когда объекты базы данных, используемые в выражении, претерпели изменения определений (DDL) с момента предыдущего использования подготовленного выражения. Кроме того, если значение search_path изменяется от одного использования к следующему, выражение будет повторно разобрано с использованием нового search_path. (Это поведение появилось в версии Digital Q.DataBase 9.3.) См. PREPARE для получения дополнительной информации о поведении подготовленных выражений.

Эту функцию следует вызывать только из подключённой функции на языке C.

SPIPlanPtr объявляется как указатель на непрозрачный тип структуры в spi.h. Не рекомендуется пытаться получить доступ к её содержимому напрямую, так как это значительно повышает вероятность поломки вашего кода в будущих версиях Digital Q.DataBase.

Имя SPIPlanPtr является в некоторой степени историческим, так как структура данных больше не обязательно содержит план выполнения.