From aefc08e4eba9085154e79ef7ad8543ea03888882 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Tue, 23 Sep 2003 19:58:50 +0000 Subject: [PATCH] Minor copy-editing for plpgsql chapter. --- doc/src/sgml/plpgsql.sgml | 155 ++++++++++++++++++++++++-------------- 1 file changed, 97 insertions(+), 58 deletions(-) diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml index d665b8986d..8db8029cf9 100644 --- a/doc/src/sgml/plpgsql.sgml +++ b/doc/src/sgml/plpgsql.sgml @@ -1,5 +1,5 @@ @@ -156,7 +156,7 @@ END; That means that your client application must send each query to - the database server, wait for it to process it, receive the + the database server, wait for it to be processed, receive the results, do some computation, then send other queries to the server. All this incurs interprocess communication and may also incur network overhead if your client is on a different machine @@ -652,7 +652,7 @@ user_id users.user_id%TYPE; an existing table or view, by using the table_name%ROWTYPE notation; or it can be declared by giving a composite type's name. - (Since every table has an associated datatype of the same name, + (Since every table has an associated composite type of the same name, it actually does not matter in PostgreSQL whether you write %ROWTYPE or not. But the form with %ROWTYPE is more portable.) @@ -916,12 +916,13 @@ tax := subtotal * 0.06; variable, or list of scalar variables. This is done by: -SELECT INTO target expressions FROM ...; +SELECT INTO target select_expressions FROM ...; where target can be a record variable, a row variable, or a comma-separated list of simple variables and - record/row fields. + record/row fields. The select_expressions + and the remainder of the command are the same as in regular SQL. @@ -1085,9 +1086,11 @@ EXECUTE command-string; The results from SELECT commands are discarded by EXECUTE, and SELECT INTO is not currently supported within EXECUTE. - So, the only way to extract a result from a dynamically-created - SELECT is to use the FOR-IN-EXECUTE form - described later. + There are two ways to extract a result from a dynamically-created + SELECT: one is to use the FOR-IN-EXECUTE + loop form described in , + and the other is to use a cursor with OPEN-FOR-EXECUTE, as + described in . @@ -1107,8 +1110,8 @@ EXECUTE ''UPDATE tbl SET '' quote_literal(text).quote_identuse in PL/pgSQLquote_literaluse - in PL/pgSQL Variables containing column and table - identifiers should be passed to function + in PL/pgSQL For safety, variables containing column and + table identifiers should be passed to function quote_ident. Variables containing values that should be literal strings in the constructed command should be passed to quote_literal. Both take the @@ -1157,8 +1160,8 @@ END; There are several ways to determine the effect of a command. The - first method is to use the GET DIAGNOSTICS, - which has the form: + first method is to use the GET DIAGNOSTICS + command, which has the form: GET DIAGNOSTICS variable = item , ... ; @@ -1179,15 +1182,15 @@ GET DIAGNOSTICS variable = item An example: -GET DIAGNOSTICS var_integer = ROW_COUNT; +GET DIAGNOSTICS integer_var = ROW_COUNT; - The second method to determine the effects of a command is the - special variable named FOUND of + The second method to determine the effects of a command is to check the + special variable named FOUND, which is of type boolean. FOUND starts out - false within each PL/pgSQL function. + false within each PL/pgSQL function call. It is set by each of the following types of statements: @@ -1200,7 +1203,7 @@ GET DIAGNOSTICS var_integer = ROW_COUNT; A PERFORM statement sets FOUND - true if it produces (discards) a row, false if no row is + true if it produces (and discards) a row, false if no row is produced. @@ -1271,7 +1274,7 @@ RETURN expression; RETURN with an expression terminates the function and returns the value of expression to the caller. This form - is to be used for PL/pgSQL functions that does + is to be used for PL/pgSQL functions that do not return a set. @@ -1287,11 +1290,14 @@ RETURN expression; The return value of a function cannot be left undefined. If control reaches the end of the top-level block of the function without hitting a RETURN statement, a run-time - error will occur. Note that if you have declared the function to + error will occur. + + + + If you have declared the function to return void, a RETURN statement - must still be specified; the expression following - RETURN is, however, optional and will be ignored in - any case. + must still be specified; but in this case the expression following + RETURN is optional and will be ignored if present. @@ -1308,9 +1314,9 @@ RETURN NEXT expression; to follow is slightly different. In that case, the individual items to return are specified in RETURN NEXT commands, and then a final RETURN command - with no arguments is used to indicate that the function has + with no argument is used to indicate that the function has finished executing. RETURN NEXT can be used - with both scalar and composite data types; in the later case, an + with both scalar and composite data types; in the latter case, an entire table of results will be returned. @@ -1347,7 +1353,7 @@ SELECT * FROM some_func(); written to disk to avoid memory exhaustion, but the function itself will not return until the entire result set has been generated. A future version of PL/pgSQL may - allow users to allow users to define set-returning functions + allow users to define set-returning functions that do not have this limitation. Currently, the point at which data begins being written to disk is controlled by the sort_mem configuration variable. Administrators @@ -1585,19 +1591,19 @@ EXIT label WHEN LOOP -- some computations - IF count > 0 THEN + IF count > 0 THEN EXIT; -- exit loop END IF; END LOOP; LOOP -- some computations - EXIT WHEN count > 0; + EXIT WHEN count > 0; -- same result as previous example END LOOP; BEGIN -- some computations - IF stocks > 100000 THEN + IF stocks > 100000 THEN EXIT; -- invalid; cannot use EXIT outside of LOOP END IF; END; @@ -1625,7 +1631,7 @@ END LOOP; For example: -WHILE amount_owed > 0 AND gift_certificate_balance > 0 LOOP +WHILE amount_owed > 0 AND gift_certificate_balance > 0 LOOP -- some computations here END LOOP; @@ -1660,19 +1666,20 @@ END LOOP; Some examples of integer FOR loops: FOR i IN 1..10 LOOP - -- some expressions here + -- some computations here RAISE NOTICE ''i is %'', i; END LOOP; FOR i IN REVERSE 10..1 LOOP - -- some expressions here + -- some computations here END LOOP; - If the lower bound is greater than the upper bound, the loop body is not - executed at all, but no error is raised. + If the lower bound is greater than the upper bound (or less than, + in the REVERSE case), the loop body is not + executed at all. No error is raised. @@ -1744,7 +1751,9 @@ END LOOP; declared as a record or row variable. If not, it's presumed to be an integer FOR loop. This can cause rather nonintuitive error messages when the true problem is, say, that one has - misspelled the variable name after the FOR. + misspelled the variable name after the FOR. Typically + the complaint will be something like missing ".." at end of SQL + expression. @@ -1766,7 +1775,7 @@ END LOOP; rows. (However, PL/pgSQL users do not normally need to worry about that, since FOR loops automatically use a cursor internally to avoid memory problems.) A more interesting usage is to - return a reference to a cursor that it has created, allowing the + return a reference to a cursor that a function has created, allowing the caller to read the rows. This provides an efficient way to return large row sets from functions. @@ -1819,8 +1828,8 @@ DECLARE Before a cursor can be used to retrieve rows, it must be opened. (This is the equivalent action to the SQL command DECLARE CURSOR.) PL/pgSQL has - three forms of the OPEN statement, two of which use unbound cursor - variables and the other uses a bound cursor variable. + three forms of the OPEN statement, two of which use unbound + cursor variables while the third uses a bound cursor variable. @@ -1958,7 +1967,7 @@ CLOSE cursor; - CLOSE closes the Portal underlying an open + CLOSE closes the portal underlying an open cursor. This can be used to release resources earlier than end of transaction, or to free up the cursor variable to be opened again. @@ -1976,18 +1985,41 @@ CLOSE curs1; PL/pgSQL functions can return cursors to the - caller. This is used to return multiple rows or columns from - the function. To do this, the function opens the cursor and returns the - cursor name to the caller. The caller can then - fetch rows from the cursor. The cursor can - be closed by the caller, or it will be closed automatically + caller. This is useful to return multiple rows or columns, + especially with very large result sets. To do this, the function + opens the cursor and returns the cursor name to the caller (or simply + opens the cursor using a portal name specified by or otherwise known + to the caller). The caller can then fetch rows from the cursor. The + cursor can be closed by the caller, or it will be closed automatically when the transaction closes. - The cursor name returned by the function can be specified by the - caller or automatically generated. The following example shows - how a cursor name can be supplied by the caller: + The portal name used for a cursor can be specified by the + programmer or automatically generated. To specify a portal name, + simply assign a string to the refcursor variable before + opening it. The string value of the refcursor variable + will be used by OPEN as the name of the underlying portal. + However, if the refcursor variable is NULL, + OPEN automatically generates a name that does not + conflict with any existing portal, and assigns it to the + refcursor variable. + + + + + A bound cursor variable is initialized to the string value + representing its name, so that the portal name is the same as + the cursor variable name, unless the programmer overrides it + by assignment before opening the cursor. But an unbound cursor + variable defaults to an initial value of NULL, so it will receive + an automatically-generated unique name, unless overridden. + + + + + The following example shows one way a cursor name can be supplied by + the caller: CREATE TABLE test (col text); @@ -2128,8 +2160,8 @@ RAISE EXCEPTION ''Inexistent ID --> %'', user_id; PL/pgSQL can be used to define trigger procedures. A trigger procedure is created with the - CREATE FUNCTION command as a function with no - arguments and a return type of trigger. Note that + CREATE FUNCTION command, declaring it as a function with + no arguments and a return type of trigger. Note that the function must be declared with no arguments even if it expects to receive arguments specified in CREATE TRIGGER --- trigger arguments are passed via TG_ARGV, as described @@ -2255,24 +2287,31 @@ RAISE EXCEPTION ''Inexistent ID --> %'', user_id; A trigger function must return either null or a record/row value having exactly the structure of the table the trigger was fired - for. The return value of a BEFORE or AFTER statement-level - trigger or an AFTER row-level trigger is ignored; it may as well - be null. However, any of these types of triggers can still - abort the entire trigger operation by raising an error. + for. Row-level triggers fired BEFORE may return null to signal the trigger manager to skip the rest of the operation for this row (i.e., subsequent triggers are not fired, and the - INSERT/UPDATE/DELETE does not occur for this row). If a nonnull + INSERT/UPDATE/DELETE does not occur + for this row). If a nonnull value is returned then the operation proceeds with that row value. Returning a row value different from the original value - of NEW alters the row that will be inserted or updated. It is - possible to replace single values directly in NEW and return NEW, + of NEW alters the row that will be inserted or updated + (but has no direct effect in the DELETE case). + To alter the row to be stored, it is possible to replace single values + directly in NEW and return the modified NEW, or to build a complete new record/row to return. + + The return value of a BEFORE or AFTER + statement-level trigger or an AFTER row-level trigger is + always ignored; it may as well be null. However, any of these types of + triggers can still abort the entire operation by raising an error. + + shows an example of a trigger procedure in PL/pgSQL. @@ -2284,7 +2323,7 @@ RAISE EXCEPTION ''Inexistent ID --> %'', user_id; This example trigger ensures that any time a row is inserted or updated in the table, the current user name and time are stamped into the - row. And it ensures that an employee's name is given and that the + row. And it checks that an employee's name is given and that the salary is a positive value. @@ -2343,7 +2382,7 @@ CREATE TRIGGER emp_stamp BEFORE INSERT OR UPDATE ON emp This section explains differences between PostgreSQL's PL/pgSQL language and Oracle's PL/SQL language, - to help developers that port applications from Oracle to + to help developers who port applications from Oracle to PostgreSQL. @@ -2815,7 +2854,7 @@ END; The PL/pgSQL version of - EXECUTE works similar to the + EXECUTE works similarly to the PL/SQL version, but you have to remember to use quote_literal(text) and quote_string(text) as described in