diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/ref/create_function.sgml | 10 | ||||
| -rw-r--r-- | doc/src/sgml/ref/prepare_transaction.sgml | 5 | ||||
| -rw-r--r-- | doc/src/sgml/ref/reset.sgml | 31 | ||||
| -rw-r--r-- | doc/src/sgml/ref/set.sgml | 57 | ||||
| -rw-r--r-- | doc/src/sgml/ref/show.sgml | 10 |
5 files changed, 83 insertions, 30 deletions
diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml index b0cfe84db1c..8c542982d52 100644 --- a/doc/src/sgml/ref/create_function.sgml +++ b/doc/src/sgml/ref/create_function.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.77 2007/09/03 18:46:29 tgl Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.78 2007/09/11 00:06:41 tgl Exp $ --> <refentry id="SQL-CREATEFUNCTION"> @@ -475,11 +475,11 @@ CREATE FUNCTION foo(int, out text) ... </para> <para> - If any <literal>SET</> clauses are attached to a function, then + If a <literal>SET</> clause is attached to a function, then the effects of a <command>SET LOCAL</> command executed inside the - function are restricted to the function: the configuration parameter's - value is restored at function exit. This is true even for parameters - not mentioned in the <literal>SET</> clause(s). However, an ordinary + function for the same variable are restricted to the function: the + configuration parameter's prior value is still restored at function exit. + However, an ordinary <command>SET</> command (without <literal>LOCAL</>) overrides the <literal>SET</> clause, much as it would do for a previous <command>SET LOCAL</> command: the effects of such a command will persist after diff --git a/doc/src/sgml/ref/prepare_transaction.sgml b/doc/src/sgml/ref/prepare_transaction.sgml index 0c8293f0ec5..5874b799303 100644 --- a/doc/src/sgml/ref/prepare_transaction.sgml +++ b/doc/src/sgml/ref/prepare_transaction.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/prepare_transaction.sgml,v 1.5 2006/09/16 00:30:19 momjian Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/prepare_transaction.sgml,v 1.6 2007/09/11 00:06:41 tgl Exp $ PostgreSQL documentation --> @@ -94,7 +94,8 @@ PREPARE TRANSACTION <replaceable class="PARAMETER">transaction_id</replaceable> </para> <para> - If the transaction modified any run-time parameters with <command>SET</>, + If the transaction modified any run-time parameters with <command>SET</> + (without the <literal>LOCAL</> option), those effects persist after <command>PREPARE TRANSACTION</>, and will not be affected by any later <command>COMMIT PREPARED</command> or <command>ROLLBACK PREPARED</command>. Thus, in this one respect diff --git a/doc/src/sgml/ref/reset.sgml b/doc/src/sgml/ref/reset.sgml index 355de891287..c90843ff583 100644 --- a/doc/src/sgml/ref/reset.sgml +++ b/doc/src/sgml/ref/reset.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/reset.sgml,v 1.35 2007/04/26 16:13:09 neilc Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/reset.sgml,v 1.36 2007/09/11 00:06:41 tgl Exp $ PostgreSQL documentation --> @@ -44,13 +44,16 @@ SET <replaceable class="parameter">configuration_parameter</replaceable> TO DEFA have had, if no <command>SET</> had ever been issued for it in the current session. The actual source of this value might be a compiled-in default, the configuration file, command-line options, - or per-database or per-user default settings. See <xref - linkend="runtime-config"> for details. + or per-database or per-user default settings. This is subtly different + from defining it as <quote>the value that the parameter had at session + start</>, because if the value came from the configuration file, it + will be reset to whatever is specified by the configuration file now. + See <xref linkend="runtime-config"> for details. </para> <para> - See the <command>SET</> reference page for details on the - transaction behavior of <command>RESET</>. + The transactional behavior of <command>RESET</> is the same as + <command>SET</>: its effects will be undone by transaction rollback. </para> </refsect1> @@ -62,8 +65,9 @@ SET <replaceable class="parameter">configuration_parameter</replaceable> TO DEFA <term><replaceable class="PARAMETER">configuration_parameter</replaceable></term> <listitem> <para> - The name of a run-time parameter. See <xref linkend="sql-set" - endterm="sql-set-title"> for a list. + Name of a settable run-time parameter. Available parameters are + documented in <xref linkend="runtime-config"> and on the + <xref linkend="sql-set" endterm="sql-set-title"> reference page. </para> </listitem> </varlistentry> @@ -83,9 +87,9 @@ SET <replaceable class="parameter">configuration_parameter</replaceable> TO DEFA <title>Examples</title> <para> - Set the <varname>geqo</> configuration variable to its default value: + Set the <varname>timezone</> configuration variable to its default value: <screen> -RESET geqo; +RESET timezone; </screen> </para> </refsect1> @@ -97,4 +101,13 @@ RESET geqo; <command>RESET</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="SQL-SET" endterm="SQL-SET-title"></member> + <member><xref linkend="SQL-SHOW" endterm="SQL-SHOW-title"></member> + </simplelist> + </refsect1> </refentry> diff --git a/doc/src/sgml/ref/set.sgml b/doc/src/sgml/ref/set.sgml index 76e8decf5c5..26ee8594b44 100644 --- a/doc/src/sgml/ref/set.sgml +++ b/doc/src/sgml/ref/set.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/set.sgml,v 1.90 2006/09/22 16:20:00 tgl Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/set.sgml,v 1.91 2007/09/11 00:06:41 tgl Exp $ PostgreSQL documentation --> @@ -40,13 +40,10 @@ SET [ SESSION | LOCAL ] TIME ZONE { <replaceable class="PARAMETER">timezone</rep </para> <para> - If <command>SET</command> or <command>SET SESSION</command> is issued - within a transaction that is later aborted, the effects of the + If <command>SET</command> (or equivalently <command>SET SESSION</command>) + is issued within a transaction that is later aborted, the effects of the <command>SET</command> command disappear when the transaction is rolled - back. (This behavior represents a change from - <productname>PostgreSQL</productname> versions prior to 7.3, where - the effects of <command>SET</command> would not roll back after a later - error.) Once the surrounding transaction is committed, the effects + back. Once the surrounding transaction is committed, the effects will persist until the end of the session, unless overridden by another <command>SET</command>. </para> @@ -59,6 +56,36 @@ SET [ SESSION | LOCAL ] TIME ZONE { <replaceable class="PARAMETER">timezone</rep seen until the end of the transaction, but afterwards (if the transaction is committed) the <command>SET</command> value will take effect. </para> + + <para> + The effects of <command>SET</command> or <command>SET LOCAL</command> are + also canceled by rolling back to a savepoint that is earlier than the + command. + </para> + + <para> + If <command>SET LOCAL</command> is used within a function that has a + <literal>SET</> option for the same variable (see + <xref linkend="sql-createfunction" endterm="sql-createfunction-title">), + the effects of the <command>SET LOCAL</command> command disappear at + function exit; that is, the value in effect when the function was called is + restored anyway. This allows <command>SET LOCAL</command> to be used for + dynamic or repeated changes of a parameter within a function, while still + having the convenience of using the <literal>SET</> option to save and + restore the caller's value. However, a regular <command>SET</> command + overrides any surrounding function's <literal>SET</> option; its effects + will persist unless rolled back. + </para> + + <note> + <para> + In <productname>PostgreSQL</productname> versions 8.0 through 8.2, + the effects of a <command>SET LOCAL</command> would be canceled by + releasing an earlier savepoint, or by successful exit from a + <application>PL/pgSQL</application> exception block. This behavior + has been changed because it was deemed unintuitive. + </para> + </note> </refsect1> <refsect1> @@ -106,8 +133,11 @@ SET [ SESSION | LOCAL ] TIME ZONE { <replaceable class="PARAMETER">timezone</rep <para> New value of parameter. Values can be specified as string constants, identifiers, numbers, or comma-separated lists of - these. <literal>DEFAULT</literal> can be used to specify - resetting the parameter to its default value. + these, as appropriate for the particular parameter. + <literal>DEFAULT</literal> can be written to specify + resetting the parameter to its default value (that is, whatever + value it would have had if no <command>SET</> had been executed + in the current session). </para> </listitem> </varlistentry> @@ -200,7 +230,9 @@ SELECT setseed(<replaceable>value</replaceable>); <term><literal>DEFAULT</literal></term> <listitem> <para> - Set the time zone to your local time zone (the one that + Set the time zone to your local time zone (that is, the + server's default value of <varname>timezone</>; if this + has not been explicitly set anywhere, it will be the zone that the server's operating system defaults to). </para> </listitem> @@ -221,7 +253,10 @@ SELECT setseed(<replaceable>value</replaceable>); <para> The function <function>set_config</function> provides equivalent - functionality. See <xref linkend="functions-admin">. + functionality; see <xref linkend="functions-admin">. + Also, it is possible to UPDATE the + <link linkend="view-pg-settings"><structname>pg_settings</structname></link> + system view to perform the equivalent of <command>SET</>. </para> </refsect1> diff --git a/doc/src/sgml/ref/show.sgml b/doc/src/sgml/ref/show.sgml index f43a0a50bd8..ab64f859428 100644 --- a/doc/src/sgml/ref/show.sgml +++ b/doc/src/sgml/ref/show.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/show.sgml,v 1.42 2006/09/16 00:30:20 momjian Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/show.sgml,v 1.43 2007/09/11 00:06:41 tgl Exp $ PostgreSQL documentation --> @@ -36,7 +36,7 @@ SHOW ALL the <envar>PGOPTIONS</envar> environmental variable (when using <application>libpq</> or a <application>libpq</>-based application), or through command-line flags when starting the - <command>postgres</command>. See <xref + <command>postgres</command> server. See <xref linkend="runtime-config"> for details. </para> </refsect1> @@ -130,7 +130,11 @@ SHOW ALL <para> The function <function>current_setting</function> produces - equivalent output. See <xref linkend="functions-admin">. + equivalent output; see <xref linkend="functions-admin">. + Also, the + <link linkend="view-pg-settings"><structname>pg_settings</structname></link> + system view produces the same information. + </para> </refsect1> |