From: Tom Lane Date: Fri, 3 May 2013 18:39:28 +0000 (-0400) Subject: Improve SPI documentation about null-flags arrays. X-Git-Tag: REL9_3_BETA1~21 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=c091c431979c182bc835b345655c1c162479aeb3;p=postgresql Improve SPI documentation about null-flags arrays. 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. --- diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml index 68693667b6..4de6a2512d 100644 --- a/doc/src/sgml/spi.sgml +++ b/doc/src/sgml/spi.sgml @@ -781,8 +781,8 @@ int SPI_execute_with_args(const char *command, Oid * argtypes - an array containing the OIDs of - the data types of the parameters + an array of length nargs, containing the + OIDs of the data types of the parameters @@ -791,7 +791,8 @@ int SPI_execute_with_args(const char *command, Datum * values - an array of actual parameter values + an array of length nargs, containing the actual + parameter values @@ -800,13 +801,20 @@ int SPI_execute_with_args(const char *command, const char * nulls - an array describing which parameters are null + an array of length nargs, describing which + parameters are null If nulls is NULL then - SPI_execute_with_args assumes that no parameters are - null. + SPI_execute_with_args assumes that no parameters + are null. Otherwise, each entry of the nulls + array should be ' ' if the corresponding parameter + value is non-null, or 'n' if the corresponding parameter + value is null. (In the latter case, the actual value in the + corresponding values entry doesn't matter.) Note + that nulls is not a text string, just an array: + it does not need a '\0' terminator. @@ -1456,15 +1464,18 @@ int SPI_execute_plan(SPIPlanPtr plan, Datum * An array describing which parameters are null. Must have same length as the statement's number of arguments. - n indicates a null value (entry in - values will be ignored); a space indicates a - nonnull value (entry in values is valid). If nulls is NULL then - SPI_execute_plan assumes that no parameters are - null. + SPI_execute_plan assumes that no parameters + are null. Otherwise, each entry of the nulls + array should be ' ' if the corresponding parameter + value is non-null, or 'n' if the corresponding parameter + value is null. (In the latter case, the actual value in the + corresponding values entry doesn't matter.) Note + that nulls is not a text string, just an array: + it does not need a '\0' terminator. @@ -1682,15 +1693,18 @@ int SPI_execp(SPIPlanPtr plan, Datum * values< An array describing which parameters are null. Must have same length as the statement's number of arguments. - n indicates a null value (entry in - values will be ignored); a space indicates a - nonnull value (entry in values is valid). If nulls is NULL then - SPI_execp assumes that no parameters are - null. + SPI_execp assumes that no parameters + are null. Otherwise, each entry of the nulls + array should be ' ' if the corresponding parameter + value is non-null, or 'n' if the corresponding parameter + value is null. (In the latter case, the actual value in the + corresponding values entry doesn't matter.) Note + that nulls is not a text string, just an array: + it does not need a '\0' terminator. @@ -1811,15 +1825,18 @@ Portal SPI_cursor_open(const char * name, SPIPlanPtr An array describing which parameters are null. Must have same length as the statement's number of arguments. - n indicates a null value (entry in - values will be ignored); a space indicates a - nonnull value (entry in values is valid). If nulls is NULL then - SPI_cursor_open assumes that no parameters are - null. + SPI_cursor_open assumes that no parameters + are null. Otherwise, each entry of the nulls + array should be ' ' if the corresponding parameter + value is non-null, or 'n' if the corresponding parameter + value is null. (In the latter case, the actual value in the + corresponding values entry doesn't matter.) Note + that nulls is not a text string, just an array: + it does not need a '\0' terminator. @@ -1930,8 +1947,8 @@ Portal SPI_cursor_open_with_args(const char *name, Oid * argtypes - an array containing the OIDs of - the data types of the parameters + an array of length nargs, containing the + OIDs of the data types of the parameters @@ -1940,7 +1957,8 @@ Portal SPI_cursor_open_with_args(const char *name, Datum * values - an array of actual parameter values + an array of length nargs, containing the actual + parameter values @@ -1949,13 +1967,20 @@ Portal SPI_cursor_open_with_args(const char *name, const char * nulls - an array describing which parameters are null + an array of length nargs, describing which + parameters are null If nulls is NULL then - SPI_cursor_open_with_args assumes that no - parameters are null. + SPI_cursor_open_with_args assumes that no parameters + are null. Otherwise, each entry of the nulls + array should be ' ' if the corresponding parameter + value is non-null, or 'n' if the corresponding parameter + value is null. (In the latter case, the actual value in the + corresponding values entry doesn't matter.) Note + that nulls is not a text string, just an array: + it does not need a '\0' terminator. @@ -3741,8 +3766,7 @@ HeapTuple SPI_modifytuple(Relation rel, HeapTuple int ncols - number of column numbers in the array - colnum + number of columns to be changed @@ -3751,8 +3775,8 @@ HeapTuple SPI_modifytuple(Relation rel, HeapTuple int * colnum - array of the numbers of the columns that are to be changed - (column numbers start at 1) + an array of length ncols, containing the numbers + of the columns that are to be changed (column numbers start at 1) @@ -3761,17 +3785,30 @@ HeapTuple SPI_modifytuple(Relation rel, HeapTuple Datum * values + an array of length ncols, containing the new values for the specified columns - const char * Nulls + const char * nulls - which new values are null, if any (see - SPI_execute_plan for the format) + an array of length ncols, describing which + new values are null + + + + If nulls is NULL then + SPI_modifytuple assumes that no new values + are null. Otherwise, each entry of the nulls + array should be ' ' if the corresponding new value is + non-null, or 'n' if the corresponding new value is + null. (In the latter case, the actual value in the corresponding + values entry doesn't matter.) Note that + nulls is not a text string, just an array: it + does not need a '\0' terminator.