mirror/postgresql
2
0
Fork 0
mirror of https://git.postgresql.org/git/postgresql.git synced 2025-01-30 19:00:29 +08:00
Code Issues Packages Projects Releases Wiki Activity

Improve SPI documentation about null-flags arrays.

Browse Source 
Clarify the description of nulls[] arguments, and use the same wording
for all SPI functions with this type of argument.  Per gripe from Yuriy
Rusinov.
This commit is contained in:
Tom Lane 2013-05-03 14:39:28 -04:00
parent 5fcf944c23
commit c091c43197
1 changed files with 71 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

105
doc/src/sgml/spi.sgml
View File

@ -781,8 +781,8 @@ int SPI_execute_with_args(const char *<parameter>command</parameter>,
<term><literal>Oid * <parameter>argtypes</parameter></literal></term> <term><literal>Oid * <parameter>argtypes</parameter></literal></term>
<listitem> <listitem>
<para> <para>
an array containing the <acronym>OID</acronym>s of an array of length <parameter>nargs</parameter>, containing the
the data types of the parameters <acronym>OID</acronym>s of the data types of the parameters
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -791,7 +791,8 @@ int SPI_execute_with_args(const char *<parameter>command</parameter>,
<term><literal>Datum * <parameter>values</parameter></literal></term> <term><literal>Datum * <parameter>values</parameter></literal></term>
<listitem> <listitem>
<para> <para>
an array of actual parameter values an array of length <parameter>nargs</parameter>, containing the actual
parameter values
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -800,13 +801,20 @@ int SPI_execute_with_args(const char *<parameter>command</parameter>,
<term><literal>const char * <parameter>nulls</parameter></literal></term> <term><literal>const char * <parameter>nulls</parameter></literal></term>
<listitem> <listitem>
<para> <para>
an array describing which parameters are null an array of length <parameter>nargs</parameter>, describing which
parameters are null
</para> </para>
<para> <para>
If <parameter>nulls</parameter> is <symbol>NULL</symbol> then If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
<function>SPI_execute_with_args</function> assumes that no parameters are <function>SPI_execute_with_args</function> assumes that no parameters
null. are null. Otherwise, each entry of the <parameter>nulls</parameter>
array should be <literal>'&nbsp;'</> if the corresponding parameter
value is non-null, or <literal>'n'</> if the corresponding parameter
value is null. (In the latter case, the actual value in the
corresponding <parameter>values</parameter> entry doesn't matter.) Note
that <parameter>nulls</parameter> is not a text string, just an array:
it does not need a <literal>'\0'</> terminator.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1456,15 +1464,18 @@ int SPI_execute_plan(SPIPlanPtr <parameter>plan</parameter>, Datum * <parameter>
<para> <para>
An array describing which parameters are null. Must have same length as An array describing which parameters are null. Must have same length as
the statement's number of arguments. the statement's number of arguments.
<literal>n</literal> indicates a null value (entry in
<parameter>values</> will be ignored); a space indicates a
nonnull value (entry in <parameter>values</> is valid).
</para> </para>
<para> <para>
If <parameter>nulls</parameter> is <symbol>NULL</symbol> then If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
<function>SPI_execute_plan</function> assumes that no parameters are <function>SPI_execute_plan</function> assumes that no parameters
null. are null. Otherwise, each entry of the <parameter>nulls</parameter>
array should be <literal>'&nbsp;'</> if the corresponding parameter
value is non-null, or <literal>'n'</> if the corresponding parameter
value is null. (In the latter case, the actual value in the
corresponding <parameter>values</parameter> entry doesn't matter.) Note
that <parameter>nulls</parameter> is not a text string, just an array:
it does not need a <literal>'\0'</> terminator.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1682,15 +1693,18 @@ int SPI_execp(SPIPlanPtr <parameter>plan</parameter>, Datum * <parameter>values<
<para> <para>
An array describing which parameters are null. Must have same length as An array describing which parameters are null. Must have same length as
the statement's number of arguments. the statement's number of arguments.
<literal>n</literal> indicates a null value (entry in
<parameter>values</> will be ignored); a space indicates a
nonnull value (entry in <parameter>values</> is valid).
</para> </para>
<para> <para>
If <parameter>nulls</parameter> is <symbol>NULL</symbol> then If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
<function>SPI_execp</function> assumes that no parameters are <function>SPI_execp</function> assumes that no parameters
null. are null. Otherwise, each entry of the <parameter>nulls</parameter>
array should be <literal>'&nbsp;'</> if the corresponding parameter
value is non-null, or <literal>'n'</> if the corresponding parameter
value is null. (In the latter case, the actual value in the
corresponding <parameter>values</parameter> entry doesn't matter.) Note
that <parameter>nulls</parameter> is not a text string, just an array:
it does not need a <literal>'\0'</> terminator.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1811,15 +1825,18 @@ Portal SPI_cursor_open(const char * <parameter>name</parameter>, SPIPlanPtr <par
<para> <para>
An array describing which parameters are null. Must have same length as An array describing which parameters are null. Must have same length as
the statement's number of arguments. the statement's number of arguments.
<literal>n</literal> indicates a null value (entry in
<parameter>values</> will be ignored); a space indicates a
nonnull value (entry in <parameter>values</> is valid).
</para> </para>
<para> <para>
If <parameter>nulls</parameter> is <symbol>NULL</symbol> then If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
<function>SPI_cursor_open</function> assumes that no parameters are <function>SPI_cursor_open</function> assumes that no parameters
null. are null. Otherwise, each entry of the <parameter>nulls</parameter>
array should be <literal>'&nbsp;'</> if the corresponding parameter
value is non-null, or <literal>'n'</> if the corresponding parameter
value is null. (In the latter case, the actual value in the
corresponding <parameter>values</parameter> entry doesn't matter.) Note
that <parameter>nulls</parameter> is not a text string, just an array:
it does not need a <literal>'\0'</> terminator.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1930,8 +1947,8 @@ Portal SPI_cursor_open_with_args(const char *<parameter>name</parameter>,
<term><literal>Oid * <parameter>argtypes</parameter></literal></term> <term><literal>Oid * <parameter>argtypes</parameter></literal></term>
<listitem> <listitem>
<para> <para>
an array containing the <acronym>OID</acronym>s of an array of length <parameter>nargs</parameter>, containing the
the data types of the parameters <acronym>OID</acronym>s of the data types of the parameters
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1940,7 +1957,8 @@ Portal SPI_cursor_open_with_args(const char *<parameter>name</parameter>,
<term><literal>Datum * <parameter>values</parameter></literal></term> <term><literal>Datum * <parameter>values</parameter></literal></term>
<listitem> <listitem>
<para> <para>
an array of actual parameter values an array of length <parameter>nargs</parameter>, containing the actual
parameter values
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1949,13 +1967,20 @@ Portal SPI_cursor_open_with_args(const char *<parameter>name</parameter>,
<term><literal>const char * <parameter>nulls</parameter></literal></term> <term><literal>const char * <parameter>nulls</parameter></literal></term>
<listitem> <listitem>
<para> <para>
an array describing which parameters are null an array of length <parameter>nargs</parameter>, describing which
parameters are null
</para> </para>
<para> <para>
If <parameter>nulls</parameter> is <symbol>NULL</symbol> then If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
<function>SPI_cursor_open_with_args</function> assumes that no <function>SPI_cursor_open_with_args</function> assumes that no parameters
parameters are null. are null. Otherwise, each entry of the <parameter>nulls</parameter>
array should be <literal>'&nbsp;'</> if the corresponding parameter
value is non-null, or <literal>'n'</> if the corresponding parameter
value is null. (In the latter case, the actual value in the
corresponding <parameter>values</parameter> entry doesn't matter.) Note
that <parameter>nulls</parameter> is not a text string, just an array:
it does not need a <literal>'\0'</> terminator.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -3741,8 +3766,7 @@ HeapTuple SPI_modifytuple(Relation <parameter>rel</parameter>, HeapTuple <parame
<term><literal>int <parameter>ncols</parameter></literal></term> <term><literal>int <parameter>ncols</parameter></literal></term>
<listitem> <listitem>
<para> <para>
number of column numbers in the array number of columns to be changed
<parameter>colnum</parameter>
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -3751,8 +3775,8 @@ HeapTuple SPI_modifytuple(Relation <parameter>rel</parameter>, HeapTuple <parame
<term><literal>int * <parameter>colnum</parameter></literal></term> <term><literal>int * <parameter>colnum</parameter></literal></term>
<listitem> <listitem>
<para> <para>
array of the numbers of the columns that are to be changed an array of length <parameter>ncols</parameter>, containing the numbers
(column numbers start at 1) of the columns that are to be changed (column numbers start at 1)
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -3761,17 +3785,30 @@ HeapTuple SPI_modifytuple(Relation <parameter>rel</parameter>, HeapTuple <parame
<term><literal>Datum * <parameter>values</parameter></literal></term> <term><literal>Datum * <parameter>values</parameter></literal></term>
<listitem> <listitem>
<para> <para>
an array of length <parameter>ncols</parameter>, containing the
new values for the specified columns new values for the specified columns
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><literal>const char * <parameter>Nulls</parameter></literal></term> <term><literal>const char * <parameter>nulls</parameter></literal></term>
<listitem> <listitem>
<para> <para>
which new values are null, if any (see an array of length <parameter>ncols</parameter>, describing which
<function>SPI_execute_plan</function> for the format) new values are null
</para>
<para>
If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
<function>SPI_modifytuple</function> assumes that no new values
are null. Otherwise, each entry of the <parameter>nulls</parameter>
array should be <literal>'&nbsp;'</> if the corresponding new value is
non-null, or <literal>'n'</> if the corresponding new value is
null. (In the latter case, the actual value in the corresponding
<parameter>values</parameter> entry doesn't matter.) Note that
<parameter>nulls</parameter> is not a text string, just an array: it
does not need a <literal>'\0'</> terminator.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>