diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml index 08f22ab64e..0e426b179b 100644 --- a/doc/src/sgml/ecpg.sgml +++ b/doc/src/sgml/ecpg.sgml @@ -1,5 +1,5 @@ @@ -284,7 +284,7 @@ EXEC SQL COMMIT; - Single-row Select: + Single-row select: EXEC SQL SELECT foo INTO :FooBar FROM table1 WHERE ascii = 'doodad'; @@ -359,7 +359,7 @@ EXEC SQL AT connection-name SELECT ...; The second option is to execute a statement to switch the current connection. That statement is: -SET CONNECTION connection-name; +EXEC SQL SET CONNECTION connection-name; This option is particularly convenient if many statements are to be executed on the same connection. @@ -392,7 +392,7 @@ SET CONNECTION connection-name; write the name of a C variable into the SQL statement, prefixed by a colon. For example: -INSERT INTO sometable VALUES (:v1, 'foo', :v2); +EXEC SQL INSERT INTO sometable VALUES (:v1, 'foo', :v2); This statements refers to two C variables named v1 and v2 and also uses a @@ -592,7 +592,7 @@ EXEC SQL BEGIN DECLARE SECTION; const char *stmt = "CREATE TABLE test1 (...);"; EXEC SQL END DECLARE SECTION; -EXECUTE IMMEDIATE :stmt; +EXEC SQL EXECUTE IMMEDIATE :stmt; You may not execute statements that retrieve data (e.g., SELECT) this way. @@ -611,9 +611,9 @@ EXEC SQL BEGIN DECLARE SECTION; const char *stmt = "INSERT INTO test1 VALUES(?, ?);"; EXEC SQL END DECLARE SECTION; -PREPARE mystmt FROM :stmt; +EXEC SQL PREPARE mystmt FROM :stmt; ... -EXECUTE mystmt USING 42, 'foobar'; +EXEC SQL EXECUTE mystmt USING 42, 'foobar'; If the statement you are executing returns values, then add an INTO clause: @@ -624,9 +624,9 @@ int v1, v2; VARCHAR v3; EXEC SQL END DECLARE SECTION; -PREPARE mystmt FROM :stmt; +EXEC SQL PREPARE mystmt FROM :stmt; ... -EXECUTE mystmt INTO v1, v2, v3 USING 37; +EXEC SQL EXECUTE mystmt INTO v1, v2, v3 USING 37; An EXECUTE command may have an INTO clause, a USING clause, @@ -668,7 +668,7 @@ EXEC SQL DEALLOCATE PREPARE name; EXEC SQL ALLOCATE DESCRIPTOR identifier; The identifier serves as the variable name of the - descriptor area. The scope of the allocated descriptor is WHAT?. + descriptor area. The scope of the allocated descriptor is WHAT?. When you don't need the descriptor anymore, you should deallocate it: diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml index 1348d59d8f..a73909fba6 100644 --- a/doc/src/sgml/extend.sgml +++ b/doc/src/sgml/extend.sgml @@ -1,5 +1,5 @@ @@ -105,52 +105,74 @@ $Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.25 2003/09/11 21:42:19 momj PostgreSQL data types are divided into base - types, composite types, domain types, and pseudo-types. + types, composite types, domains, and pseudo-types. - - Base types are those, like int4, that are implemented - below the level of the SQL language (typically in a low-level - language such as C). They generally correspond to - what are often known as abstract data types. - PostgreSQL - can only operate on such types through functions provided - by the user and only understands the behavior of such - types to the extent that the user describes them. Base types are - further subdivided into scalar and array types. For each scalar type, - a corresponding array type is automatically created that can hold - variable-size arrays of that scalar type. - + + Base Types - - Composite types, or row types, are created whenever the user creates a - table; it's also possible to define a stand-alone composite - type with no associated table. A composite type is simply a list of - base types with associated field names. A value of a composite type - is a row or record of field values. The user can access the component - fields from SQL queries. - + + Base types are those, like int4, that are + implemented below the level of the SQL language + (typically in a low-level language such as C). They generally + correspond to what are often known as abstract data types. + PostgreSQL can only operate on such + types through functions provided by the user and only understands + the behavior of such types to the extent that the user describes + them. Base types are further subdivided into scalar and array + types. For each scalar type, a corresponding array type is + automatically created that can hold variable-size arrays of that + scalar type. + + - - A domain type is based on a particular base - type and for many purposes is interchangeable with its base type. - However, a domain may have constraints that restrict its valid values - to a subset of what the underlying base type would allow. Domains can - be created by simple SQL commands. - + + Composite Types - - Finally, there are a few pseudo-types for special purposes. - Pseudo-types cannot appear as fields of tables or composite types, but - they can be used to declare the argument and result types of functions. - This provides a mechanism within the type system to identify special - classes of functions. lists the existing - pseudo-types. - + + Composite types, or row types, are created whenever the user + creates a table; it's also possible to define a + stand-alone composite type with no associated table. A + composite type is simply a list of base types with associated + field names. A value of a composite type is a row or record of + field values. The user can access the component fields from + SQL queries. + + + + + Domains + + + A domain is based on a particular base type and for many purposes + is interchangeable with its base type. However, a domain may + have constraints that restrict its valid values to a subset of + what the underlying base type would allow. + + + + Domains can be created using the SQL commands + CREATE DOMAIN. Their creation and use is not + discussed in this chapter. + + + + + Pseudo-Types + + + There are a few pseudo-types for special purposes. + Pseudo-types cannot appear as columns of tables or attributes of + composite types, but they can be used to declare the argument and + result types of functions. This provides a mechanism within the + type system to identify special classes of functions. lists the existing + pseudo-types. + + - Polymorphic Types and Functions + Polymorphic Types polymorphic type diff --git a/doc/src/sgml/install-win32.sgml b/doc/src/sgml/install-win32.sgml index 7beb5ea97d..5feb4e5a2c 100644 --- a/doc/src/sgml/install-win32.sgml +++ b/doc/src/sgml/install-win32.sgml @@ -1,5 +1,5 @@ @@ -109,7 +109,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/install-win32.sgml,v 1.15 2003/11/04 09:55: psql is compiled as a console - application. As the Win32 console windows use a different + application. As the Windows console windows use a different encoding than the rest of the system, you must take special care when using 8-bit characters at the psql prompt. When psql detects a problematic diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 4431df7911..f1b96e2aff 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,5 +1,5 @@ @@ -355,7 +355,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); whilst doing so. The point of this approach is that the waits for I/O to complete can occur in the application's main loop, rather than down inside - PQconnectdb(), and so the application can manage this + PQconnectdb, and so the application can manage this operation in parallel with other activities. @@ -829,8 +829,8 @@ has been sent to the server and not yet completed. PQtransactionStatus will give incorrect results when using -a PostgreSQL 7.3 server that has AUTOCOMMIT -set to OFF. The server-side autocommit feature has been +a PostgreSQL 7.3 server that has the parameter autocommit +set to off. The server-side autocommit feature has been deprecated and does not exist in later server versions. @@ -1028,7 +1028,7 @@ PGresult *PQexec(PGconn *conn, const char *command); It is allowed to include multiple SQL commands (separated by semicolons) in the command string. Multiple queries sent in a single PQexec call are processed in a single transaction, unless there are explicit -BEGIN/COMMIT commands included in the query string to divide it into multiple +BEGIN/COMMIT commands included in the query string to divide it into multiple transactions. Note however that the returned PGresult structure describes only the result of the last command executed from the string. Should one of the commands fail, processing of the string stops with @@ -1737,7 +1737,7 @@ This function is deprecated (except for its use in connection with COPY), because it is possible for a single PGresult to contain text data in some columns and binary data in others. -PQfformat() is preferred. PQbinaryTuples +PQfformat is preferred. PQbinaryTuples returns 1 only if all columns of the result are binary (format 1). @@ -2068,7 +2068,7 @@ unsigned char *PQescapeBytea(const unsigned char *from, PQescapeBytea returns an escaped version of the from parameter binary string in memory allocated with malloc(). This memory must be freed - using PQfreemem() when the result is no longer needed. + using PQfreemem when the result is no longer needed. The return string has all special characters replaced so that they can be properly processed by the PostgreSQL string literal parser, and @@ -2102,7 +2102,7 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); It returns a pointer to a buffer allocated with malloc(), or null on error, and puts the size of the buffer in to_length. The result must be - freed using PQfreemem() when it is no longer needed. + freed using PQfreemem when it is no longer needed. @@ -2122,9 +2122,9 @@ void PQfreemem(void *ptr); PQescapeBytea, PQunescapeBytea, and PQnotifies. - It is needed by Win32, which can not free memory across + It is needed by Microsoft Windows, which cannot free memory across DLLs, unless multithreaded DLLs ( in VC6) are used. - On other platforms it is the same as free(). + On other platforms, this function is the same as the standard library function free(). @@ -2420,7 +2420,7 @@ while waiting for input from the database server. However, it is still possible that the application will block waiting to send output to the server. This is relatively uncommon but can happen if very long SQL commands or data values are sent. (It is much more probable if the application -sends data via COPY IN, however.) To prevent this possibility and achieve +sends data via COPY IN, however.) To prevent this possibility and achieve completely nonblocking database operation, the following additional functions may be used. @@ -2634,15 +2634,10 @@ After processing a PGnotify object returned by PGnotify pointer; the relname and extra fields do not represent separate allocations. +(At present, the extra field is unused and will +always point to an empty string.) - - - At present the extra field is unused and will - always point to an empty string. - - - In PostgreSQL 6.4 and later, @@ -2657,28 +2652,28 @@ of asynchronous notification. -PQnotifies() does not actually read data from the server; it just +PQnotifies does not actually read data from the server; it just returns messages previously absorbed by another libpq function. In prior releases of libpq, the only way to ensure timely receipt of NOTIFY messages was to constantly submit commands, -even empty ones, and then check PQnotifies() after each -PQexec(). While this still works, it is +even empty ones, and then check PQnotifies after each +PQexec. While this still works, it is deprecated as a waste of processing power. A better way to check for NOTIFY messages when you have no useful commands to execute is to call -PQconsumeInput(), then check -PQnotifies(). +PQconsumeInput, then check +PQnotifies. You can use select() to wait for data to arrive from the server, thereby using no CPU power unless there is something -to do. (See PQsocket() to obtain the file descriptor +to do. (See PQsocket to obtain the file descriptor number to use with select().) Note that this will work OK whether you submit commands with PQsendQuery/PQgetResult or simply use PQexec. You should, however, remember to -check PQnotifies() after each +check PQnotifies after each PQgetResult or PQexec, to see if any notifications came in during the processing of the command. @@ -2813,7 +2808,7 @@ int PQputCopyData(PGconn *conn, -Transmits the COPY data in the specified buffer, of length +Transmits the COPY data in the specified buffer, of length nbytes, to the server. The result is 1 if the data was sent, zero if it was not sent because the attempt would block (this case is only possible if the connection is in nonblocking mode), or -1 if an error occurred. @@ -2896,7 +2891,7 @@ int PQgetCopyData(PGconn *conn, -Attempts to obtain another row of data from the server during a COPY. +Attempts to obtain another row of data from the server during a COPY. Data is always returned one data row at a time; if only a partial row is available, it is not returned. Successful return of a data row involves allocating a chunk of memory to hold the data. The @@ -2910,17 +2905,17 @@ buffer is returned. A non-NULL result buffer must be freed usi When a row is successfully returned, the return value is the number of data bytes in the row (this will always be greater than zero). The returned string is always null-terminated, though this is probably only -useful for textual COPY. A result of zero indicates that the COPY is +useful for textual COPY. A result of zero indicates that the COPY is still in progress, but no row is yet available (this is only possible when async is true). A -result of -1 indicates that the COPY is done. +result of -1 indicates that the COPY is done. A result of -2 indicates that an error occurred (consult PQerrorMessage for the reason). When async is true (not zero), PQgetCopyData -will not block waiting for input; it will return zero if the COPY is still +will not block waiting for input; it will return zero if the COPY is still in progress but no complete row is available. (In this case wait for read-ready before trying again; it does not matter whether you call PQconsumeInput.) When async is @@ -2992,7 +2987,7 @@ for a terminator line). PQgetlineAsyncPQgetlineAsync - Reads a row of COPY data + Reads a row of COPY data (transmitted by the server) into a buffer without blocking. @@ -3031,7 +3026,7 @@ a whole row will be returned at one time. But if the buffer offered by the caller is too small to hold a row sent by the server, then a partial data row will be returned. With textual data this can be detected by testing whether the last returned byte is \n or not. (In a binary -COPY, actual parsing of the COPY data format will be needed to make the +COPY, actual parsing of the COPY data format will be needed to make the equivalent determination.) The returned string is not null-terminated. (If you want to add a terminating null, be sure to pass a bufsize one smaller @@ -3065,7 +3060,7 @@ call; it is okay to send a partial line or multiple lines per call. Before PostgreSQL protocol 3.0, it was necessary for the application to explicitly send the two characters \. as a final line to indicate to the server that it had -finished sending COPY data. While this still works, it is deprecated and the +finished sending COPY data. While this still works, it is deprecated and the special meaning of \. can be expected to be removed in a future release. It is sufficient to call PQendcopy after having sent the actual data. @@ -3162,17 +3157,19 @@ Determines the verbosity of messages returned by PQerrorMessage and PQresultErrorMessage. typedef enum { - PQERRORS_TERSE, PQERRORS_DEFAULT, PQERRORS_VERBOSE + PQERRORS_TERSE, + PQERRORS_DEFAULT, + PQERRORS_VERBOSE } PGVerbosity; PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); PQsetErrorVerbosity sets the verbosity mode, returning the connection's previous setting. -In TERSE mode, returned messages include severity, primary text, and position -only; this will normally fit on a single line. The DEFAULT mode produces +In terse mode, returned messages include severity, primary text, and position +only; this will normally fit on a single line. The default mode produces messages that include the above plus any detail, hint, or context fields -(these may span multiple lines). The VERBOSE mode includes all available +(these may span multiple lines). The VERBOSE mode includes all available fields. Changing the verbosity does not affect the messages available from already-existing PGresult objects, only subsequently-created ones. @@ -3568,7 +3565,7 @@ If the permissions are less strict than this, the file will be ignored. -Threading Behavior +Behavior in Threaded Programs threads @@ -3576,11 +3573,14 @@ If the permissions are less strict than this, the file will be ignored. -libpq is thread-safe if the library is -compiled using configure's ---enable-thread-safety command-line option. -(In addition, you might need to use other threading command-line -options to compile your client code.) +libpq is reentrant and thread-safe if the +configure command-line option +--enable-thread-safety has been used when the PostgreSQL +distribution was built. +In addition, you might need to use additional compiler command-line +options when you compile your application code. Refer to your system's +documentation for information about how to build thread-enabled +applications. diff --git a/doc/src/sgml/lobj.sgml b/doc/src/sgml/lobj.sgml index 4cdac668f0..ce91bc3728 100644 --- a/doc/src/sgml/lobj.sgml +++ b/doc/src/sgml/lobj.sgml @@ -1,5 +1,5 @@ @@ -299,7 +299,7 @@ int lo_unlink(PGconn *conn, Oid lobjId); -Server-side Functions +Server-Side Functions There are two built-in server-side functions, diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml index 3ea9461452..8104c08150 100644 --- a/doc/src/sgml/plpgsql.sgml +++ b/doc/src/sgml/plpgsql.sgml @@ -1,5 +1,5 @@ @@ -114,25 +114,25 @@ END; Because PL/pgSQL saves execution plans - in this way, SQL commands that appear directly in a - PL/pgSQL function must refer to the - same tables and columns on every execution; that is, you cannot use - a parameter as the name of a table or column in an SQL command. To get - around this restriction, you can construct dynamic commands using - the PL/pgSQL EXECUTE - statement --- at the price of constructing a new execution plan on - every execution. + in this way, SQL commands that appear directly in a + PL/pgSQL function must refer to the + same tables and columns on every execution; that is, you cannot use + a parameter as the name of a table or column in an SQL command. To get + around this restriction, you can construct dynamic commands using + the PL/pgSQL EXECUTE + statement --- at the price of constructing a new execution plan on + every execution. - - The PL/pgSQL - EXECUTE statement is not related to the - EXECUTE statement supported by the - PostgreSQL server. The server's - EXECUTE statement cannot be used within - PL/pgSQL functions (and is not needed). - + + The PL/pgSQL + EXECUTE statement is not related to the + EXECUTE statement supported by the + PostgreSQL server. The server's + EXECUTE statement cannot be used within + PL/pgSQL functions (and is not needed). + @@ -195,7 +195,7 @@ END; PL/pgSQL functions may also be declared to accept - and return the polymorphic types + and return the polymorphic types anyelement and anyarray. The actual data types handled by a polymorphic function can vary from call to call, as discussed in . @@ -230,7 +230,7 @@ END; the function definition. For example: CREATE OR REPLACE FUNCTION testfunc(integer) RETURNS integer AS ' - .... + .... end; ' LANGUAGE plpgsql; @@ -255,7 +255,7 @@ end; - Handling of Quote Marks + Handling of Quotation Marks Since the code of a PL/pgSQL function is specified in @@ -265,13 +265,13 @@ end; rather complicated code at times, especially if you are writing a function that generates other functions, as in the example in . This chart may be useful - as a summary of the needed numbers of quote marks in + as a summary of the needed numbers of quotation marks in various situations. - 1 quote mark + 1 quotation mark To begin and end the function body, for example: @@ -279,14 +279,14 @@ end; CREATE FUNCTION foo() RETURNS integer AS '...' LANGUAGE plpgsql; - Anywhere within the function body, quote marks must + Anywhere within the function body, quotation marks must appear in pairs. - 2 quote marks + 2 quotation marks For string literals inside the function body, for example: @@ -303,10 +303,10 @@ SELECT * FROM users WHERE f_name='foobar'; - 4 quote marks + 4 quotation marks - When you need a single quote in a string constant inside the function + When you need a single quotation mark in a string constant inside the function body, for example: a_output := a_output || '' AND name LIKE ''''foobar'''' AND xyz'' @@ -318,10 +318,10 @@ a_output := a_output || '' AND name LIKE ''''foobar'''' AND xyz'' - 6 quote marks + 6 quotation marks - When a single quote in a string inside the function body is + When a single quotation mark in a string inside the function body is adjacent to the end of that string constant, for example: a_output := a_output || '' AND name LIKE ''''foobar'''''' @@ -333,11 +333,11 @@ a_output := a_output || '' AND name LIKE ''''foobar'''''' - 10 quote marks + 10 quotation marks - When you want two single quotes in a string constant (which - accounts for 8 quotes) and this is adjacent to the end of that + When you want two single quotation marks in a string constant (which + accounts for 8 quotation marks) and this is adjacent to the end of that string constant (2 more). You will probably only need that if you are writing a function that generates other functions. For example: @@ -358,7 +358,7 @@ if v_... like ''...'' then return ''...''; end if; - A different approach is to escape quote marks in the function body + A different approach is to escape quotation marks in the function body with a backslash rather than by doubling them. With this method you'll find yourself writing things like \'\' instead of ''''. Some find this easier to keep track of, some @@ -568,7 +568,7 @@ END; linkend="extend-types-polymorphic">). This allows the function to access its actual return type as shown in . - $0 is initialized to NULL and can be modified by + $0 is initialized to null and can be modified by the function, so it can be used to hold the return value if desired, though that is not required. $0 can also be given an alias. For example, this function works on any data type @@ -689,14 +689,12 @@ END; - - Record Types + + Record Types - name RECORD; - Record variables are similar to row-type variables, but they have no @@ -721,36 +719,38 @@ END; - - <literal>RENAME</> + + <literal>RENAME</> - RENAME oldname TO newname; - Using the RENAME declaration you can change the name of a variable, - record or row. This is primarily useful if NEW or OLD should be - referenced by another name inside a trigger procedure. See also ALIAS. - + + Using the RENAME declaration you can change the + name of a variable, record or row. This is primarily useful if + NEW or OLD should be + referenced by another name inside a trigger procedure. See also + ALIAS. + - - Examples: + + Examples: RENAME id TO user_id; RENAME this_var TO that_var; - + - - RENAME appears to be broken as of PostgreSQL - 7.3. Fixing this is of low priority, since ALIAS covers most of - the practical uses of RENAME. - + + RENAME appears to be broken as of + PostgreSQL 7.3. Fixing this is of low priority, + since ALIAS covers most of the practical uses + of RENAME. + - - + @@ -1159,9 +1159,9 @@ END; Obtaining the Result Status - There are several ways to determine the effect of a command. The - first method is to use the GET DIAGNOSTICS - command, which has the form: + There are several ways to determine the effect of a command. The + first method is to use the GET DIAGNOSTICS + command, which has the form: GET DIAGNOSTICS variable = item , ... ; @@ -1192,49 +1192,49 @@ GET DIAGNOSTICS integer_var = ROW_COUNT; type boolean. FOUND starts out false within each PL/pgSQL function call. It is set by each of the following types of statements: - - - - A SELECT INTO statement sets - FOUND true if it returns a row, false if no - row is returned. - - - - - A PERFORM statement sets FOUND - true if it produces (and discards) a row, false if no row is - produced. - - - - - UPDATE, INSERT, and DELETE - statements set FOUND true if at least one - row is affected, false if no row is affected. - - - - - A FETCH statement sets FOUND - true if it returns a row, false if no row is returned. - - - - - A FOR statement sets FOUND true - if it iterates one or more times, else false. This applies to - all three variants of the FOR statement (integer - FOR loops, record-set FOR loops, and - dynamic record-set FOR - loops). FOUND is only set when the - FOR loop exits: inside the execution of the loop, - FOUND is not modified by the - FOR statement, although it may be changed by the - execution of other statements within the loop body. - - - + + + + A SELECT INTO statement sets + FOUND true if it returns a row, false if no + row is returned. + + + + + A PERFORM statement sets FOUND + true if it produces (and discards) a row, false if no row is + produced. + + + + + UPDATE, INSERT, and DELETE + statements set FOUND true if at least one + row is affected, false if no row is affected. + + + + + A FETCH statement sets FOUND + true if it returns a row, false if no row is returned. + + + + + A FOR statement sets FOUND true + if it iterates one or more times, else false. This applies to + all three variants of the FOR statement (integer + FOR loops, record-set FOR loops, and + dynamic record-set FOR + loops). FOUND is only set when the + FOR loop exits: inside the execution of the loop, + FOUND is not modified by the + FOR statement, although it may be changed by the + execution of other statements within the loop body. + + + FOUND is a local variable; any changes to it affect only the current PL/pgSQL function. @@ -1583,7 +1583,7 @@ EXIT label WHEN If WHEN is present, loop exit occurs only if the specified condition - is true, otherwise control passes to the statement after EXIT. + is true, otherwise control passes to the statement after EXIT. @@ -1624,8 +1624,8 @@ END LOOP; The WHILE statement repeats a sequence of statements so long as the condition expression - evaluates to true. The condition is checked just before - each entry to the loop body. + evaluates to true. The condition is checked just before + each entry to the loop body. @@ -1654,12 +1654,12 @@ END LOOP; This form of FOR creates a loop that iterates over a range of integer - values. The variable + values. The variable name is automatically defined as type integer and exists only inside the loop. The two expressions giving the lower and upper bound of the range are evaluated once when entering the loop. The iteration step is normally 1, but is -1 when REVERSE is - specified. + specified. @@ -1678,7 +1678,7 @@ END LOOP; If the lower bound is greater than the upper bound (or less than, - in the REVERSE case), the loop body is not + in the REVERSE case), the loop body is not executed at all. No error is raised. @@ -1841,13 +1841,13 @@ OPEN unbound-cursor FOR SELECT ...; The cursor variable is opened and given the specified query to - execute. The cursor cannot be open already, and it must have been - declared as an unbound cursor (that is, as a simple - refcursor variable). The SELECT query - is treated in the same way as other SELECT - statements in PL/pgSQL: PL/pgSQL - variable names are substituted, and the query plan is cached for - possible reuse. + execute. The cursor cannot be open already, and it must have been + declared as an unbound cursor (that is, as a simple + refcursor variable). The SELECT query + is treated in the same way as other SELECT + statements in PL/pgSQL: PL/pgSQL + variable names are substituted, and the query plan is cached for + possible reuse. @@ -1865,14 +1865,14 @@ OPEN curs1 FOR SELECT * FROM foo WHERE key = mykey; OPEN unbound-cursor FOR EXECUTE query-string; - - The cursor variable is opened and given the specified query to - execute. The cursor cannot be open already, and it must have been - declared as an unbound cursor (that is, as a simple - refcursor variable). The query is specified as a string - expression in the same way as in the EXECUTE - command. As usual, this gives flexibility so the query can vary - from one run to the next. + + The cursor variable is opened and given the specified query to + execute. The cursor cannot be open already, and it must have been + declared as an unbound cursor (that is, as a simple + refcursor variable). The query is specified as a string + expression in the same way as in the EXECUTE + command. As usual, this gives flexibility so the query can vary + from one run to the next. @@ -1890,14 +1890,14 @@ OPEN curs1 FOR EXECUTE ''SELECT * FROM '' || quote_ident($1); OPEN bound-cursor ( argument_values ) ; - - This form of OPEN is used to open a cursor - variable whose query was bound to it when it was declared. The - cursor cannot be open already. A list of actual argument value - expressions must appear if and only if the cursor was declared to - take arguments. These values will be substituted in the query. - The query plan for a bound cursor is always considered cacheable; - there is no equivalent of EXECUTE in this case. + + This form of OPEN is used to open a cursor + variable whose query was bound to it when it was declared. The + cursor cannot be open already. A list of actual argument value + expressions must appear if and only if the cursor was declared to + take arguments. These values will be substituted in the query. + The query plan for a bound cursor is always considered cacheable; + there is no equivalent of EXECUTE in this case. @@ -1941,13 +1941,13 @@ OPEN curs3(42); FETCH cursor INTO target; - - FETCH retrieves the next row from the - cursor into a target, which may be a row variable, a record - variable, or a comma-separated list of simple variables, just like - SELECT INTO. As with SELECT - INTO, the special variable FOUND may - be checked to see whether a row was obtained or not. + + FETCH retrieves the next row from the + cursor into a target, which may be a row variable, a record + variable, or a comma-separated list of simple variables, just like + SELECT INTO. As with SELECT + INTO, the special variable FOUND may + be checked to see whether a row was obtained or not. @@ -1968,8 +1968,8 @@ CLOSE cursor; 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. + cursor. This can be used to release resources earlier than end of + transaction, or to free up the cursor variable to be opened again. @@ -1986,40 +1986,40 @@ CLOSE curs1; PL/pgSQL functions can return cursors to the 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 + 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 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. + 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. + 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 the null value initially , 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: + the caller: CREATE TABLE test (col text); @@ -2104,7 +2104,7 @@ RAISE level ' PL/Python - Python Procedural Language @@ -17,18 +17,6 @@ createlang plpythonu dbname. - - - As of PostgreSQL 7.4, - PL/Python is only available as an untrusted language - (meaning it does not offer any way of restricting what users - can do in it). It has therefore been renamed to plpythonu. - The trusted variant plpython may become available again in - future, if a new secure execution mechanism is developed by the Python - community. - - - If a language is installed into template1, all subsequently @@ -36,6 +24,15 @@ + + As of PostgreSQL 7.4, PL/Python is only + available as an untrusted language (meaning it does not + offer any way of restricting what users can do in it). It has + therefore been renamed to plpythonu. The trusted + variant plpython may become available again in future, + if a new secure execution mechanism is developed in Python. + + Users of source packages must specially enable the build of diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml index c8b55ac4e7..b3542d2caf 100644 --- a/doc/src/sgml/pltcl.sgml +++ b/doc/src/sgml/pltcl.sgml @@ -1,5 +1,5 @@ @@ -136,7 +136,7 @@ CREATE FUNCTION tcl_max(integer, integer) RETURNS integer AS ' As shown above, - to return a NULL value from a PL/Tcl function, execute + to return a null value from a PL/Tcl function, execute return_null. This can be done whether the function is strict or not. diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml index d094e3970e..e4d83e6986 100644 --- a/doc/src/sgml/ref/create_function.sgml +++ b/doc/src/sgml/ref/create_function.sgml @@ -1,5 +1,5 @@ @@ -95,7 +95,7 @@ CREATE [ OR REPLACE ] FUNCTION name The data type(s) of the function's arguments (optionally schema-qualified), if any. The argument types may be base, complex, or - domain types, or copy the type of an existing column. + domains, or copy the type of an existing column. The type of a column is referenced by writing @@ -120,8 +120,8 @@ CREATE [ OR REPLACE ] FUNCTION name The return data type (optionally schema-qualified). The return type - may be specified as a base, complex, or domain type, - or may copy the type of an existing column. See the description + may be a base type, complex type, or a domain, + or may be specified to copy the type of an existing column. See the description under argtype above on how to reference the type of an existing column. diff --git a/doc/src/sgml/release.sgml b/doc/src/sgml/release.sgml index fca6a0fbe4..6a1c90a7ba 100644 --- a/doc/src/sgml/release.sgml +++ b/doc/src/sgml/release.sgml @@ -1,5 +1,5 @@ @@ -878,12 +878,12 @@ zero-row record variable (Tom) Allow PQcmdTuples() to return row counts for MOVE and FETCH (Neil) -Add PQfreemem() for freeing memory on Win32, suggest for NOTIFY (Bruce) +Add PQfreemem() for freeing memory on Windows, suggest for NOTIFY (Bruce) - Win32 requires that memory allocated in a library be freed by a + Windows requires that memory allocated in a library be freed by a function in the same library, hence free() doesn't work for freeing memory allocated by libpq. PQfreemem() is the proper way to free - libpq memory, especially on Win32, and is recommended for other + libpq memory, especially on Windows, and is recommended for other platforms as well. @@ -961,8 +961,8 @@ zero-row record variable (Tom) Convert administration scripts to C (Peter) Bison >= 1.85 is now required to build the PostgreSQL grammar, if building from CVS Merge documentation into one book (Peter) -Add Win32 compatibility functions (Bruce) -Allow client interfaces to compile under MinGW/Win32 (Bruce) +Add Windows compatibility functions (Bruce) +Allow client interfaces to compile under MinGW (Bruce) New ereport() function for error reporting (Tom) Support Intel Linux compiler (Peter) Improve Linux startup scripts (Slawomir Sudnik, Darko Prenosil) @@ -1794,7 +1794,7 @@ of locale? Fix for sending large queries over non-blocking connections (Bernhard Herzog) Fix for libpq using timers on Win9X (David Ford) Allow libpq notify to handle servers with different-length identifiers (Tom) -Add libpq PQescapeString() and PQescapeBytea() to Win32 (Bruce) +Add libpq PQescapeString() and PQescapeBytea() to Windows (Bruce) Fix for SSL with non-blocking connections (Jack Bates) Add libpq connection timeout parameter (Denis A Ustimenko) @@ -1846,7 +1846,7 @@ of locale? Always enable multibyte in compile, remove --enable-multibyte option (Tatsuo) Always enable locale in compile, remove --enable-locale option (Peter) Fix for Win9x DLL creation (Magnus Naeslund) -Fix for link() usage by WAL code on Win32, BeOS (Jason Tishler) +Fix for link() usage by WAL code on Windows, BeOS (Jason Tishler) Add sys/types.h to c.h, remove from main files (Peter, Bruce) Fix AIX hang on SMP machines (Tomoyuki Niijima) AIX SMP hang fix (Tomoyuki Niijima) @@ -1871,7 +1871,7 @@ of locale? New Polish FAQ (Marcin Mazurek) Add Posix semaphore support (Tom) Document need for reindex (Bruce) -Rename some internal identifiers to simplify Win32 compile (Jan, Katherine Ward) +Rename some internal identifiers to simplify Windows compile (Jan, Katherine Ward) Add documentation on computing disk space (Bruce) Remove KSQO from GUC (Bruce) Fix memory leak in rtree (Kenneth Been) @@ -2588,8 +2588,8 @@ of locale? Configure, dynamic loader, and shared library fixes (Peter E) Fixes in QNX 4 port (Bernd Tegge) -Fixes in Cygwin and Win32 ports (Jason Tishler, Gerhard Haring, Dmitry Yurtaev, Darko Prenosil, Mikhail Terekhov) -Fix for Win32 socket communication failures (Magnus, Mikhail Terekhov) +Fixes in Cygwin and Windows ports (Jason Tishler, Gerhard Haring, Dmitry Yurtaev, Darko Prenosil, Mikhail Terekhov) +Fix for Windows socket communication failures (Magnus, Mikhail Terekhov) Hurd compile fix (Oliver Elphick) BeOS fixes (Cyril Velter) Remove configure --enable-unicode-conversion, now enabled by multibyte (Tatsuo) @@ -3675,7 +3675,7 @@ Clean up #include in /include directory (Bruce) Add scripts for checking includes (Bruce) Remove un-needed #include's from *.c files (Bruce) Change #include's to use <> and "" as appropriate (Bruce) -Enable WIN32 compilation of libpq +Enable Windows compilation of libpq Alpha spinlock fix from Uncle George gatgul@voicenet.com Overhaul of optimizer data structures (Tom) Fix to cygipc library (Yutaka Tanida) @@ -3688,7 +3688,7 @@ New platform-specific regression handling (Tom) Rename oid8 -> oidvector and int28 -> int2vector (Bruce) Included all yacc and lex files into the distribution (Peter E.) Remove lextest, no longer needed (Peter E) -Fix for libpq and psql on Win32 (Magnus) +Fix for libpq and psql on Windows (Magnus) Internally change datetime and timespan into timestamp and interval (Thomas) Fix for plpgsql on BSD/OS Add SQL_ASCII test case to the regression test (Tatsuo) @@ -3772,7 +3772,7 @@ Fixes for CASE in WHERE join clauses(Tom) Fix BTScan abort(Tom) Repair the check for redundant UNIQUE and PRIMARY KEY indexes(Thomas) Improve it so that it checks for multicolumn constraints(Thomas) -Fix for Win32 making problem with MB enabled(Hiroki Kataoka) +Fix for Windows making problem with MB enabled(Hiroki Kataoka) Allow BSD yacc and bison to compile pl code(Bruce) Fix SET NAMES working int8 fixes(Thomas) @@ -4230,7 +4230,7 @@ Source Tree Changes ------------------- Improve port matching(Tom) Portability fixes for SunOS -Add NT/Win32 backend port and enable dynamic loading(Magnus and Daniel Horak) +Add Windows NT backend port and enable dynamic loading(Magnus and Daniel Horak) New port to Cobalt Qube(Mips) running Linux(Tatsuo) Port to NetBSD/m68k(Mr. Mutsuki Nakajima) Port to NetBSD/sun3(Mr. Mutsuki Nakajima) @@ -4338,7 +4338,7 @@ Timezone fixes(Tom) HP-UX fixes(Tom) Use implicit type coercion for matching DEFAULT values(Thomas) Add routines to help with single-byte (internal) character type(Thomas) -Compilation of libpq for Win32 fixes(Magnus) +Compilation of libpq for Windows fixes(Magnus) Upgrade to PyGreSQL 2.2(D'Arcy) @@ -4523,7 +4523,7 @@ New contrib/lo code for large object orphan removal(Peter) New psql command "SET CLIENT_ENCODING TO 'encoding'" for multibytes feature, see /doc/README.mb(Tatsuo) /contrib/noupdate code to revoke update permission on a column -libpq can now be compiled on win32(Magnus) +libpq can now be compiled on Windows(Magnus) Add PQsetdbLogin() in libpq New 8-byte integer type, checked by configure for OS support(Thomas) Better support for quoted table/column names(Thomas) @@ -4586,7 +4586,7 @@ New setval() command to set sequence value(Massimo) Auto-remove unix socket file on start-up if no postmaster running(Massimo) Conditional trace package(Massimo) New UNLISTEN command(Massimo) -psql and libpq now compile under win32 using win32.mak(Magnus) +psql and libpq now compile under Windows using win32.mak(Magnus) Lo_read no longer stores trailing NULL(Bruce) Identifiers are now truncated to 31 characters internally(Bruce) Createuser options now availble on the command line @@ -5551,7 +5551,7 @@ new OS-specific template files(Marc) no more need to edit Makefile.global(Marc) re-arrange include files(Marc) nextstep patches (Gregor Hoffleit) -removed WIN32-specific code(Bruce) +removed Windows-specific code(Bruce) removed postmaster -e option, now only postgres -e option (Bruce) merge duplicate library code in front/backends(Martin) now works with eBones, international Kerberos(Jun) diff --git a/doc/src/sgml/typeconv.sgml b/doc/src/sgml/typeconv.sgml index a0dd5cf032..391176d682 100644 --- a/doc/src/sgml/typeconv.sgml +++ b/doc/src/sgml/typeconv.sgml @@ -1,5 +1,5 @@ @@ -289,7 +289,7 @@ candidate remains, use it; else continue to the next step. Run through all candidates and keep those with the most exact matches -on input types. (Domain types are considered the same as their base type +on input types. (Domains are considered the same as their base type for this purpose.) Keep all candidates if none have any exact matches. If only one candidate remains, use it; else continue to the next step. @@ -542,7 +542,7 @@ candidate remains, use it; else continue to the next step. Run through all candidates and keep those with the most exact matches -on input types. (Domain types are considered the same as their base type +on input types. (Domains are considered the same as their base type for this purpose.) Keep all candidates if none have any exact matches. If only one candidate remains, use it; else continue to the next step. diff --git a/doc/src/sgml/xaggr.sgml b/doc/src/sgml/xaggr.sgml index 8f1bda7e79..939faac3ae 100644 --- a/doc/src/sgml/xaggr.sgml +++ b/doc/src/sgml/xaggr.sgml @@ -1,5 +1,5 @@ @@ -140,16 +140,20 @@ CREATE AGGREGATE array_accum ( SELECT attrelid::regclass, array_accum(attname) -FROM pg_attribute WHERE attnum > 0 -AND attrelid = 'pg_user'::regclass GROUP BY attrelid; + FROM pg_attribute + WHERE attnum > 0 AND attrelid = 'pg_user'::regclass + GROUP BY attrelid; + attrelid | array_accum ----------+----------------------------------------------------------------------------- pg_user | {usename,usesysid,usecreatedb,usesuper,usecatupd,passwd,valuntil,useconfig} (1 row) SELECT attrelid::regclass, array_accum(atttypid) -FROM pg_attribute WHERE attnum > 0 -AND attrelid = 'pg_user'::regclass GROUP BY attrelid; + FROM pg_attribute + WHERE attnum > 0 AND attrelid = 'pg_user'::regclass + GROUP BY attrelid; + attrelid | array_accum ----------+------------------------------ pg_user | {19,23,16,16,16,25,702,1009} diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index 0c1a7610df..42358431f7 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -1,5 +1,5 @@ @@ -392,9 +392,9 @@ SELECT name(emp) AS youngster result of the first function to it: -CREATE FUNCTION getname(emp) RETURNS text AS -'SELECT $1.name;' -LANGUAGE SQL; +CREATE FUNCTION getname(emp) RETURNS text AS ' + SELECT $1.name; +' LANGUAGE SQL; SELECT getname(new_emp()); getname @@ -538,12 +538,12 @@ SELECT name, listchildren(name) FROM nodes; SQL functions may be declared to accept and - return the polymorphic types - anyelement and anyarray. - See for a more detailed explanation - of polymorphic functions. Here is a polymorphic function - make_array that builds up an array from two - arbitrary data type elements: + return the polymorphic types anyelement and + anyarray. See for a more detailed + explanation of polymorphic functions. Here is a polymorphic + function make_array that builds up an array + from two arbitrary data type elements: CREATE FUNCTION make_array(anyelement, anyelement) RETURNS anyarray AS ' SELECT ARRAY[$1, $2]; @@ -567,7 +567,7 @@ SELECT make_array(1, 2) AS intarray, make_array('a'::text, 'b') AS textarray; Without the typecast, you will get errors like this: -ERROR: could not determine ANYARRAY/ANYELEMENT type because input is UNKNOWN +ERROR: could not determine "anyarray"/"anyelement" type because input has type "unknown" @@ -576,7 +576,7 @@ ERROR: could not determine ANYARRAY/ANYELEMENT type because input is UNKNOWN It is permitted to have polymorphic arguments with a deterministic return type, but the converse is not. For example: -CREATE FUNCTION is_greater(anyelement, anyelement) RETURNS bool AS ' +CREATE FUNCTION is_greater(anyelement, anyelement) RETURNS boolean AS ' SELECT $1 > $2; ' LANGUAGE SQL; @@ -589,8 +589,8 @@ SELECT is_greater(1, 2); CREATE FUNCTION invalid_func() RETURNS anyelement AS ' SELECT 1; ' LANGUAGE SQL; -ERROR: cannot determine result datatype -DETAIL: A function returning ANYARRAY or ANYELEMENT must have at least one argument of either type. +ERROR: cannot determine result data type +DETAIL: A function returning "anyarray" or "anyelement" must have at least one argument of either type. @@ -758,15 +758,13 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision that fails as well, the load will fail. - - - The user ID the PostgreSQL server runs - as must be able to traverse the path to the file you intend to - load. Making the file or a higher-level directory not readable - and/or not executable by the postgres user is a - common mistake. - - + + The user ID the PostgreSQL server runs + as must be able to traverse the path to the file you intend to + load. Making the file or a higher-level directory not readable + and/or not executable by the postgres + user is a common mistake. + In any case, the file name that is given in the @@ -785,16 +783,14 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision - - - After it is used for the first time, a dynamically loaded object - file is retained in memory. Future calls in the same session to the - function(s) in that file will only incur the small overhead of a symbol - table lookup. If you need to force a reload of an object file, for - example after recompiling it, use the LOAD command or - begin a fresh session. - - + + After it is used for the first time, a dynamically loaded object + file is retained in memory. Future calls in the same session to + the function(s) in that file will only incur the small overhead of + a symbol table lookup. If you need to force a reload of an object + file, for example after recompiling it, use the LOAD + command or begin a fresh session. + It is recommended to locate shared libraries either relative to @@ -805,17 +801,15 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision command pg_config --pkglibdir. - - - Before PostgreSQL release 7.2, only exact - absolute paths to object files could be specified in CREATE - FUNCTION. This approach is now deprecated since it makes the - function definition unnecessarily unportable. It's best to specify - just the shared library name with no path nor extension, and let - the search mechanism provide that information instead. - - - + + Before PostgreSQL release 7.2, only + exact absolute paths to object files could be specified in + CREATE FUNCTION. This approach is now deprecated + since it makes the function definition unnecessarily unportable. + It's best to specify just the shared library name with no path nor + extension, and let the search mechanism provide that information + instead. + @@ -1685,8 +1679,7 @@ c_overpaid(PG_FUNCTION_ARGS) c_overpaid in SQL: -CREATE FUNCTION c_overpaid(emp, integer) - RETURNS boolean +CREATE FUNCTION c_overpaid(emp, integer) RETURNS boolean AS 'DIRECTORY/funcs', 'c_overpaid' LANGUAGE C; @@ -2111,7 +2104,7 @@ CREATE OR REPLACE FUNCTION testpassbyval(integer, integer) RETURNS SETOF __testp C-language functions may be declared to accept and - return the polymorphic types + return the polymorphic types anyelement and anyarray. See for a more detailed explanation of polymorphic functions. When function arguments or return types @@ -2178,14 +2171,13 @@ make_array(PG_FUNCTION_ARGS) make_array in SQL: -CREATE FUNCTION make_array(anyelement) - RETURNS anyarray +CREATE FUNCTION make_array(anyelement) RETURNS anyarray AS 'DIRECTORY/funcs', 'make_array' - LANGUAGE 'C' STRICT; + LANGUAGE C STRICT; - Note the use of STRICT; this is essential since the code is not - bothering to test for a NULL input. + Note the use of STRICT; this is essential + since the code is not bothering to test for a null input.