<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>SPI_execute_with_args</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 9.3.9 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="Interface Functions"
HREF="spi-interface.html"><LINK
REL="PREVIOUS"
TITLE="SPI_exec"
HREF="spi-spi-exec.html"><LINK
REL="NEXT"
TITLE="SPI_prepare"
HREF="spi-spi-prepare.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2015-06-13T20:07:22"></HEAD
><BODY
CLASS="REFENTRY"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
><A
HREF="index.html"
>PostgreSQL 9.3.9 Documentation</A
></TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
TITLE="SPI_exec"
HREF="spi-spi-exec.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="spi-interface.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="20%"
ALIGN="right"
VALIGN="top"
><A
TITLE="SPI_prepare"
HREF="spi-spi-prepare.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="SPI-SPI-EXECUTE-WITH-ARGS"
></A
>SPI_execute_with_args</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN62008"
></A
><H2
>Name</H2
>SPI_execute_with_args -- execute a command with out-of-line parameters</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN62013"
></A
><H2
>Synopsis</H2
><PRE
CLASS="SYNOPSIS"
>int SPI_execute_with_args(const char *<TT
CLASS="PARAMETER"
>command</TT
>,
int <TT
CLASS="PARAMETER"
>nargs</TT
>, Oid *<TT
CLASS="PARAMETER"
>argtypes</TT
>,
Datum *<TT
CLASS="PARAMETER"
>values</TT
>, const char *<TT
CLASS="PARAMETER"
>nulls</TT
>,
bool <TT
CLASS="PARAMETER"
>read_only</TT
>, long <TT
CLASS="PARAMETER"
>count</TT
>)</PRE
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN62022"
></A
><H2
>Description</H2
><P
> <CODE
CLASS="FUNCTION"
>SPI_execute_with_args</CODE
> executes a command that might
include references to externally supplied parameters. The command text
refers to a parameter as <TT
CLASS="LITERAL"
>$<TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
></TT
>, and
the call specifies data types and values for each such symbol.
<TT
CLASS="PARAMETER"
>read_only</TT
> and <TT
CLASS="PARAMETER"
>count</TT
> have
the same interpretation as in <CODE
CLASS="FUNCTION"
>SPI_execute</CODE
>.
</P
><P
> The main advantage of this routine compared to
<CODE
CLASS="FUNCTION"
>SPI_execute</CODE
> is that data values can be inserted
into the command without tedious quoting/escaping, and thus with much
less risk of SQL-injection attacks.
</P
><P
> Similar results can be achieved with <CODE
CLASS="FUNCTION"
>SPI_prepare</CODE
> followed by
<CODE
CLASS="FUNCTION"
>SPI_execute_plan</CODE
>; however, when using this function
the query plan is always customized to the specific parameter values
provided.
For one-time query execution, this function should be preferred.
If the same command is to be executed with many different parameters,
either method might be faster, depending on the cost of re-planning
versus the benefit of custom plans.
</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN62036"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="LITERAL"
>const char * <TT
CLASS="PARAMETER"
>command</TT
></TT
></DT
><DD
><P
> command string
</P
></DD
><DT
><TT
CLASS="LITERAL"
>int <TT
CLASS="PARAMETER"
>nargs</TT
></TT
></DT
><DD
><P
> number of input parameters (<TT
CLASS="LITERAL"
>$1</TT
>, <TT
CLASS="LITERAL"
>$2</TT
>, etc.)
</P
></DD
><DT
><TT
CLASS="LITERAL"
>Oid * <TT
CLASS="PARAMETER"
>argtypes</TT
></TT
></DT
><DD
><P
> an array of length <TT
CLASS="PARAMETER"
>nargs</TT
>, containing the
<ACRONYM
CLASS="ACRONYM"
>OID</ACRONYM
>s of the data types of the parameters
</P
></DD
><DT
><TT
CLASS="LITERAL"
>Datum * <TT
CLASS="PARAMETER"
>values</TT
></TT
></DT
><DD
><P
> an array of length <TT
CLASS="PARAMETER"
>nargs</TT
>, containing the actual
parameter values
</P
></DD
><DT
><TT
CLASS="LITERAL"
>const char * <TT
CLASS="PARAMETER"
>nulls</TT
></TT
></DT
><DD
><P
> an array of length <TT
CLASS="PARAMETER"
>nargs</TT
>, describing which
parameters are null
</P
><P
> If <TT
CLASS="PARAMETER"
>nulls</TT
> is <TT
CLASS="SYMBOL"
>NULL</TT
> then
<CODE
CLASS="FUNCTION"
>SPI_execute_with_args</CODE
> assumes that no parameters
are null. Otherwise, each entry of the <TT
CLASS="PARAMETER"
>nulls</TT
>
array should be <TT
CLASS="LITERAL"
>' '</TT
> if the corresponding parameter
value is non-null, or <TT
CLASS="LITERAL"
>'n'</TT
> if the corresponding parameter
value is null. (In the latter case, the actual value in the
corresponding <TT
CLASS="PARAMETER"
>values</TT
> entry doesn't matter.) Note
that <TT
CLASS="PARAMETER"
>nulls</TT
> is not a text string, just an array:
it does not need a <TT
CLASS="LITERAL"
>'\0'</TT
> terminator.
</P
></DD
><DT
><TT
CLASS="LITERAL"
>bool <TT
CLASS="PARAMETER"
>read_only</TT
></TT
></DT
><DD
><P
><TT
CLASS="LITERAL"
>true</TT
> for read-only execution</P
></DD
><DT
><TT
CLASS="LITERAL"
>long <TT
CLASS="PARAMETER"
>count</TT
></TT
></DT
><DD
><P
> maximum number of rows to return,
or <TT
CLASS="LITERAL"
>0</TT
> for no limit
</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN62099"
></A
><H2
>Return Value</H2
><P
> The return value is the same as for <CODE
CLASS="FUNCTION"
>SPI_execute</CODE
>.
</P
><P
> <TT
CLASS="VARNAME"
>SPI_processed</TT
> and
<TT
CLASS="VARNAME"
>SPI_tuptable</TT
> are set as in
<CODE
CLASS="FUNCTION"
>SPI_execute</CODE
> if successful.
</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-spi-exec.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-spi-prepare.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>SPI_exec</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="spi-interface.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>SPI_prepare</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
