SPI_execute_extended — 执行带行外参数的命令
int SPI_execute_extended(const char *command, const SPIExecuteOptions *options)
SPI_execute_extended 执行一条可能包含对
外部提供的参数的引用的命令。
命令文本以
$ 引用一个参数,
noptions->params 对象
(如果提供)为每个这样的符号提供值和类型信息。
各种执行选项也可以在
options 结构中指定。
options->params 对象通常应当把每个
参数标记为
PARAM_FLAG_CONST 标志,
因为查询总是使用一次性计划。
如果
options->dest 不是 NULL,
结果元组会在执行器生成它们时被传给那个对象,
而不是被累积在
SPI_tuptable 中。
使用调用者提供的
DestReceiver 对象对可能生成许多元组的查询
特别有帮助,因为数据可以被即时处理而不必在内存中
累积。
const char * command命令字符串
const SPIExecuteOptions * options包含可选参数的结构
调用者应当始终把整个
options
结构清零,然后填入想设置的字段。
这确保代码的前向兼容性,因为将来加入该结构的任何字段
都会被定义为在为零时以向后兼容的方式行事。
当前可用的
options 字段有:
ParamListInfo params包含查询参数类型和值的数据结构;没有则为 NULL
bool read_onlytrue 表示只读执行
bool allow_nonatomic
为
true 允许以非原子方式执行 CALL 和 DO
语句(但除非把
SPI_OPT_NONATOMIC 标志传给了
SPI_connect_ext,否则此字段会被
忽略)
bool must_return_tuples
如果为
true,当查询不是会返回元组的种类时抛出
错误(这不禁止它恰好返回零个元组的情形)
uint64 tcount
要返回的最大行数,
0 表示没有限制
DestReceiver * dest
将接收查询发出的任何元组的
DestReceiver 对象;如果为 NULL,
结果元组会像在
SPI_execute 中那样被累积到一个
SPI_tuptable 结构中
ResourceOwner owner
这个字段是为了与
SPI_execute_plan_extended 保持一致而
存在的,但它会被忽略,因为
SPI_execute_extended 使用的计划永远不会
被保存。
返回值与
SPI_execute 相同。
当
options->dest 为 NULL 时,
SPI_processed 和
SPI_tuptable 的设置方式与
SPI_execute 相同。
当
options->dest 不为 NULL 时,
SPI_processed 被设为零,
SPI_tuptable 被设为 NULL。
如果需要元组计数,调用者的
DestReceiver 对象必须自行计算。