PostgreSQL 中文参考文档
🌐 英文原版 官方 ↗

SPI_cursor_open

SPI_cursor_open — 用 SPI_prepare 创建的语句建立一个游标

Synopsis

Portal SPI_cursor_open(const char * name, SPIPlanPtr plan,
                       Datum * values, const char * nulls,
                       bool read_only)

描述

SPI_cursor_open 建立一个游标 (内部是一个 portal),它将执行由 SPI_prepare 预备的 语句。 这些参数的含义与 SPI_execute_plan 的相应参数 相同。

与直接执行语句相比,使用游标有两个好处。 首先,结果行可以一次取回少数几行, 避免了返回许多行的查询导致的内存耗尽。 其次,一个 portal 的寿命可以超过当前的 C 函数 (实际上,它可以活到当前事务结束)。 把 portal 名返回给 C 函数的调用者提供了一种把行集作为结果返回 的方式。

传入的参数数据会被复制进游标的 portal, 因此它可以在游标仍然存在时被释放。

参数

const char * name

portal 的名称,或 NULL 让系统选择一个名称

SPIPlanPtr plan

预备语句(由 SPI_prepare 返回)

Datum * values

实际参数值的数组。 长度必须与语句的参数数量相同。

const char * nulls

描述哪些参数为空的数组。 长度必须与语句的参数数量相同。

如果 nulls 为 NULL,则 SPI_cursor_open 假定没有参数是 空的。 否则, nulls 数组的每个条目在相应参数值非空时应为 ' ',在相应参数值为空时应为 'n'。 (在后一种情况下,相应 values 条目中的实际值无关紧要。) 注意, nulls 不是一个文本字符串,只是一个 数组:它不需要 '\0' 终止符。

bool read_only

true 表示只读执行

返回值

指向包含该游标的 portal 的指针。 注意没有错误返回约定;任何错误都会通过 elog 报告。