Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commitc091c43

Browse files
committed
Improve SPI documentation about null-flags arrays.
Clarify the description of nulls[] arguments, and use the same wordingfor all SPI functions with this type of argument. Per gripe from YuriyRusinov.
1 parent5fcf944 commitc091c43

File tree

1 file changed

+71
-34
lines changed

1 file changed

+71
-34
lines changed

‎doc/src/sgml/spi.sgml

Lines changed: 71 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -781,8 +781,8 @@ int SPI_execute_with_args(const char *<parameter>command</parameter>,
781781
<term><literal>Oid * <parameter>argtypes</parameter></literal></term>
782782
<listitem>
783783
<para>
784-
an arraycontaining the <acronym>OID</acronym>s of
785-
the data types of the parameters
784+
an arrayof length <parameter>nargs</parameter>, containing the
785+
<acronym>OID</acronym>s ofthe data types of the parameters
786786
</para>
787787
</listitem>
788788
</varlistentry>
@@ -791,7 +791,8 @@ int SPI_execute_with_args(const char *<parameter>command</parameter>,
791791
<term><literal>Datum * <parameter>values</parameter></literal></term>
792792
<listitem>
793793
<para>
794-
an array of actual parameter values
794+
an array of length <parameter>nargs</parameter>, containing the actual
795+
parameter values
795796
</para>
796797
</listitem>
797798
</varlistentry>
@@ -800,13 +801,20 @@ int SPI_execute_with_args(const char *<parameter>command</parameter>,
800801
<term><literal>const char * <parameter>nulls</parameter></literal></term>
801802
<listitem>
802803
<para>
803-
an array describing which parameters are null
804+
an array of length <parameter>nargs</parameter>, describing which
805+
parameters are null
804806
</para>
805807

806808
<para>
807809
If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
808-
<function>SPI_execute_with_args</function> assumes that no parameters are
809-
null.
810+
<function>SPI_execute_with_args</function> assumes that no parameters
811+
are null. Otherwise, each entry of the <parameter>nulls</parameter>
812+
array should be <literal>'&nbsp;'</> if the corresponding parameter
813+
value is non-null, or <literal>'n'</> if the corresponding parameter
814+
value is null. (In the latter case, the actual value in the
815+
corresponding <parameter>values</parameter> entry doesn't matter.) Note
816+
that <parameter>nulls</parameter> is not a text string, just an array:
817+
it does not need a <literal>'\0'</> terminator.
810818
</para>
811819
</listitem>
812820
</varlistentry>
@@ -1456,15 +1464,18 @@ int SPI_execute_plan(SPIPlanPtr <parameter>plan</parameter>, Datum * <parameter>
14561464
<para>
14571465
An array describing which parameters are null. Must have same length as
14581466
the statement's number of arguments.
1459-
<literal>n</literal> indicates a null value (entry in
1460-
<parameter>values</> will be ignored); a space indicates a
1461-
nonnull value (entry in <parameter>values</> is valid).
14621467
</para>
14631468

14641469
<para>
14651470
If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
1466-
<function>SPI_execute_plan</function> assumes that no parameters are
1467-
null.
1471+
<function>SPI_execute_plan</function> assumes that no parameters
1472+
are null. Otherwise, each entry of the <parameter>nulls</parameter>
1473+
array should be <literal>'&nbsp;'</> if the corresponding parameter
1474+
value is non-null, or <literal>'n'</> if the corresponding parameter
1475+
value is null. (In the latter case, the actual value in the
1476+
corresponding <parameter>values</parameter> entry doesn't matter.) Note
1477+
that <parameter>nulls</parameter> is not a text string, just an array:
1478+
it does not need a <literal>'\0'</> terminator.
14681479
</para>
14691480
</listitem>
14701481
</varlistentry>
@@ -1682,15 +1693,18 @@ int SPI_execp(SPIPlanPtr <parameter>plan</parameter>, Datum * <parameter>values<
16821693
<para>
16831694
An array describing which parameters are null. Must have same length as
16841695
the statement's number of arguments.
1685-
<literal>n</literal> indicates a null value (entry in
1686-
<parameter>values</> will be ignored); a space indicates a
1687-
nonnull value (entry in <parameter>values</> is valid).
16881696
</para>
16891697

16901698
<para>
16911699
If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
1692-
<function>SPI_execp</function> assumes that no parameters are
1693-
null.
1700+
<function>SPI_execp</function> assumes that no parameters
1701+
are null. Otherwise, each entry of the <parameter>nulls</parameter>
1702+
array should be <literal>'&nbsp;'</> if the corresponding parameter
1703+
value is non-null, or <literal>'n'</> if the corresponding parameter
1704+
value is null. (In the latter case, the actual value in the
1705+
corresponding <parameter>values</parameter> entry doesn't matter.) Note
1706+
that <parameter>nulls</parameter> is not a text string, just an array:
1707+
it does not need a <literal>'\0'</> terminator.
16941708
</para>
16951709
</listitem>
16961710
</varlistentry>
@@ -1811,15 +1825,18 @@ Portal SPI_cursor_open(const char * <parameter>name</parameter>, SPIPlanPtr <par
18111825
<para>
18121826
An array describing which parameters are null. Must have same length as
18131827
the statement's number of arguments.
1814-
<literal>n</literal> indicates a null value (entry in
1815-
<parameter>values</> will be ignored); a space indicates a
1816-
nonnull value (entry in <parameter>values</> is valid).
18171828
</para>
18181829

18191830
<para>
18201831
If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
1821-
<function>SPI_cursor_open</function> assumes that no parameters are
1822-
null.
1832+
<function>SPI_cursor_open</function> assumes that no parameters
1833+
are null. Otherwise, each entry of the <parameter>nulls</parameter>
1834+
array should be <literal>'&nbsp;'</> if the corresponding parameter
1835+
value is non-null, or <literal>'n'</> if the corresponding parameter
1836+
value is null. (In the latter case, the actual value in the
1837+
corresponding <parameter>values</parameter> entry doesn't matter.) Note
1838+
that <parameter>nulls</parameter> is not a text string, just an array:
1839+
it does not need a <literal>'\0'</> terminator.
18231840
</para>
18241841
</listitem>
18251842
</varlistentry>
@@ -1930,8 +1947,8 @@ Portal SPI_cursor_open_with_args(const char *<parameter>name</parameter>,
19301947
<term><literal>Oid * <parameter>argtypes</parameter></literal></term>
19311948
<listitem>
19321949
<para>
1933-
an arraycontaining the <acronym>OID</acronym>s of
1934-
the data types of the parameters
1950+
an arrayof length <parameter>nargs</parameter>, containing the
1951+
<acronym>OID</acronym>s ofthe data types of the parameters
19351952
</para>
19361953
</listitem>
19371954
</varlistentry>
@@ -1940,7 +1957,8 @@ Portal SPI_cursor_open_with_args(const char *<parameter>name</parameter>,
19401957
<term><literal>Datum * <parameter>values</parameter></literal></term>
19411958
<listitem>
19421959
<para>
1943-
an array of actual parameter values
1960+
an array of length <parameter>nargs</parameter>, containing the actual
1961+
parameter values
19441962
</para>
19451963
</listitem>
19461964
</varlistentry>
@@ -1949,13 +1967,20 @@ Portal SPI_cursor_open_with_args(const char *<parameter>name</parameter>,
19491967
<term><literal>const char * <parameter>nulls</parameter></literal></term>
19501968
<listitem>
19511969
<para>
1952-
an array describing which parameters are null
1970+
an array of length <parameter>nargs</parameter>, describing which
1971+
parameters are null
19531972
</para>
19541973

19551974
<para>
19561975
If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
1957-
<function>SPI_cursor_open_with_args</function> assumes that no
1958-
parameters are null.
1976+
<function>SPI_cursor_open_with_args</function> assumes that no parameters
1977+
are null. Otherwise, each entry of the <parameter>nulls</parameter>
1978+
array should be <literal>'&nbsp;'</> if the corresponding parameter
1979+
value is non-null, or <literal>'n'</> if the corresponding parameter
1980+
value is null. (In the latter case, the actual value in the
1981+
corresponding <parameter>values</parameter> entry doesn't matter.) Note
1982+
that <parameter>nulls</parameter> is not a text string, just an array:
1983+
it does not need a <literal>'\0'</> terminator.
19591984
</para>
19601985
</listitem>
19611986
</varlistentry>
@@ -3741,8 +3766,7 @@ HeapTuple SPI_modifytuple(Relation <parameter>rel</parameter>, HeapTuple <parame
37413766
<term><literal>int <parameter>ncols</parameter></literal></term>
37423767
<listitem>
37433768
<para>
3744-
number of column numbers in the array
3745-
<parameter>colnum</parameter>
3769+
number of columns to be changed
37463770
</para>
37473771
</listitem>
37483772
</varlistentry>
@@ -3751,8 +3775,8 @@ HeapTuple SPI_modifytuple(Relation <parameter>rel</parameter>, HeapTuple <parame
37513775
<term><literal>int * <parameter>colnum</parameter></literal></term>
37523776
<listitem>
37533777
<para>
3754-
array ofthe numbers of thecolumns that are to be changed
3755-
(column numbers start at 1)
3778+
anarray oflength <parameter>ncols</parameter>, containing thenumbers
3779+
of the columns that are to be changed(column numbers start at 1)
37563780
</para>
37573781
</listitem>
37583782
</varlistentry>
@@ -3761,17 +3785,30 @@ HeapTuple SPI_modifytuple(Relation <parameter>rel</parameter>, HeapTuple <parame
37613785
<term><literal>Datum * <parameter>values</parameter></literal></term>
37623786
<listitem>
37633787
<para>
3788+
an array of length <parameter>ncols</parameter>, containing the
37643789
new values for the specified columns
37653790
</para>
37663791
</listitem>
37673792
</varlistentry>
37683793

37693794
<varlistentry>
3770-
<term><literal>const char * <parameter>Nulls</parameter></literal></term>
3795+
<term><literal>const char * <parameter>nulls</parameter></literal></term>
37713796
<listitem>
37723797
<para>
3773-
which new values are null, if any (see
3774-
<function>SPI_execute_plan</function> for the format)
3798+
an array of length <parameter>ncols</parameter>, describing which
3799+
new values are null
3800+
</para>
3801+
3802+
<para>
3803+
If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
3804+
<function>SPI_modifytuple</function> assumes that no new values
3805+
are null. Otherwise, each entry of the <parameter>nulls</parameter>
3806+
array should be <literal>'&nbsp;'</> if the corresponding new value is
3807+
non-null, or <literal>'n'</> if the corresponding new value is
3808+
null. (In the latter case, the actual value in the corresponding
3809+
<parameter>values</parameter> entry doesn't matter.) Note that
3810+
<parameter>nulls</parameter> is not a text string, just an array: it
3811+
does not need a <literal>'\0'</> terminator.
37753812
</para>
37763813
</listitem>
37773814
</varlistentry>

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp