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 68693667b66caafe420d1ea4a1286d8db2a85205..4de6a2512d40bda46a24502954f5d5ecd9f71674 100644 (file)
--- 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.