<HTML ><HEAD ><TITLE >SPI_cursor_open</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.73 "><LINK REV="MADE" HREF="mailto:pgsql-docs@postgresql.org"><LINK REL="HOME" TITLE="PostgreSQL 7.3.2 Documentation" HREF="index.html"><LINK REL="UP" TITLE="Interface Functions" HREF="spi.html#SPI-INTERFACE"><LINK REL="PREVIOUS" TITLE="SPI_execp" HREF="spi-spiexecp.html"><LINK REL="NEXT" TITLE="SPI_cursor_find" HREF="spi-spicursor-find.html"><LINK REL="STYLESHEET" TYPE="text/css" HREF="stylesheet.css"><META NAME="creation" CONTENT="2003-02-03T20:17:34"></HEAD ><BODY CLASS="REFENTRY" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="3" ALIGN="center" >PostgreSQL 7.3.2 Documentation</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="bottom" ><A HREF="spi-spiexecp.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="80%" ALIGN="center" VALIGN="bottom" ></TD ><TD WIDTH="10%" ALIGN="right" VALIGN="bottom" ><A HREF="spi-spicursor-find.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><H1 ><A NAME="SPI-SPICURSOR-OPEN" >SPI_cursor_open</A ></H1 ><DIV CLASS="REFNAMEDIV" ><A NAME="AEN34045" ></A ><H2 >Name</H2 >SPI_cursor_open -- Sets up a cursor using a plan created with <TT CLASS="FUNCTION" >SPI_prepare</TT ><A NAME="IX-SPI-SPICURSOR-OPEN-1" ></A ><A NAME="IX-SPI-SPICURSOR-OPEN-2" ></A ></DIV ><DIV CLASS="REFSYNOPSISDIV" ><A NAME="AEN34054" ></A ><H2 >Synopsis</H2 ><PRE CLASS="SYNOPSIS" >SPI_cursor_open(<TT CLASS="REPLACEABLE" ><I >name</I ></TT >, <TT CLASS="REPLACEABLE" ><I >plan</I ></TT >, <TT CLASS="REPLACEABLE" ><I >values</I ></TT >, <TT CLASS="REPLACEABLE" ><I >nulls</I ></TT >)</PRE ><DIV CLASS="REFSECT2" ><A NAME="R2-SPI-SPICURSOR-OPEN-1" ></A ><H3 >Inputs</H3 ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >char *<TT CLASS="REPLACEABLE" ><I >name</I ></TT ></DT ><DD ><P >Name for portal, or NULL to let the system select a name</P ></DD ><DT >void *<TT CLASS="REPLACEABLE" ><I >plan</I ></TT ></DT ><DD ><P >Execution plan</P ></DD ><DT >Datum *<TT CLASS="REPLACEABLE" ><I >values</I ></TT ></DT ><DD ><P >Actual parameter values</P ></DD ><DT >char *<TT CLASS="REPLACEABLE" ><I >nulls</I ></TT ></DT ><DD ><P >Array describing which parameters are NULLs <P ></P ><TABLE BORDER="0" ><TBODY ><TR ><TD ><TT CLASS="LITERAL" >n</TT > indicates NULL (values[] entry ignored)</TD ></TR ><TR ><TD >space indicates not NULL (values[] entry is valid)</TD ></TR ></TBODY ></TABLE ><P ></P ></P ></DD ></DL ></DIV ></DIV ><DIV CLASS="REFSECT2" ><A NAME="R2-SPI-SPICURSOR-OPEN-2" ></A ><H3 >Outputs</H3 ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Portal</DT ><DD ><P > Pointer to Portal containing cursor, or NULL on error</P ></DD ></DL ></DIV ></DIV ></DIV ><DIV CLASS="REFSECT1" ><A NAME="R1-SPI-SPICURSOR-OPEN-1" ></A ><H2 >Description</H2 ><P ><TT CLASS="FUNCTION" >SPI_cursor_open</TT > sets up a cursor (internally, a Portal) that will execute a plan prepared by <TT CLASS="FUNCTION" >SPI_prepare</TT >.</P ><P > Using a cursor instead of executing the plan directly has two benefits. First, the result rows can be retrieved a few at a time, avoiding memory overrun for queries that return many rows. Second, a Portal can outlive the current procedure (it can, in fact, live to the end of the current transaction). Returning the portal name to the procedure's caller provides a way of returning a rowset result.</P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="R1-SPI-SPICURSOR-OPEN-2" ></A ><H2 >Usage</H2 ><P > If <TT CLASS="REPLACEABLE" ><I >nulls</I ></TT > is NULL then <TT CLASS="FUNCTION" >SPI_cursor_open</TT > assumes that all parameters (if any) are NOT NULL.</P ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="spi-spiexecp.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="index.html" ACCESSKEY="H" >Home</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="spi-spicursor-find.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >SPI_execp</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="spi.html#SPI-INTERFACE" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >SPI_cursor_find</TD ></TR ></TABLE ></DIV ></BODY ></HTML >
