From 797c2b2501fc94d50b111dcd2226180ee31890f5 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Tue, 28 Dec 2004 22:47:15 +0000 Subject: [PATCH] More minor updates and copy-editing. --- doc/src/sgml/ecpg.sgml | 40 ++++++------ doc/src/sgml/external-projects.sgml | 87 ++++++++++++------------- doc/src/sgml/information_schema.sgml | 12 ++-- doc/src/sgml/libpq.sgml | 96 ++++++++++++++++++---------- doc/src/sgml/lobj.sgml | 52 ++++++++------- 5 files changed, 160 insertions(+), 127 deletions(-) diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml index b240ce3ffb..153f9bd197 100644 --- a/doc/src/sgml/ecpg.sgml +++ b/doc/src/sgml/ecpg.sgml @@ -1,5 +1,5 @@ @@ -19,7 +19,7 @@ $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.59 2003/12/26 20:00:00 meskes Exp - Admittedly, this documentation is quite incomplete. But since this + This documentation is quite incomplete. But since this interface is standardized, additional information can be found in many resources about SQL. @@ -31,9 +31,9 @@ $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.59 2003/12/26 20:00:00 meskes Exp An embedded SQL program consists of code written in an ordinary programming language, in this case C, mixed with SQL commands in specially marked sections. To build the program, the source code - is first passed to the embedded SQL preprocessor, which converts it + is first passed through the embedded SQL preprocessor, which converts it to an ordinary C program, and afterwards it can be processed by a C - compilation tool chain. + compiler. @@ -53,7 +53,7 @@ $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.59 2003/12/26 20:00:00 meskes Exp - As indicated, programs written for the embedded + As already stated, programs written for the embedded SQL interface are normal C programs with special code inserted to perform database-related actions. This special code always has the form @@ -61,8 +61,8 @@ $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.59 2003/12/26 20:00:00 meskes Exp EXEC SQL ...; These statements syntactically take the place of a C statement. - Depending on the particular statement, they may appear in the - global context or within a function. Embedded + Depending on the particular statement, they may appear at the + global level or within a function. Embedded SQL statements follow the case-sensitivity rules of normal SQL code, and not those of C. @@ -326,9 +326,9 @@ EXEC SQL COMMIT; In the default mode, statements are committed only when EXEC SQL COMMIT is issued. The embedded SQL - interface also supports autocommit of transactions (as known from - other interfaces) via the command-line option - to ecpg (see below) or via the EXEC SQL + interface also supports autocommit of transactions (similar to + libpq behavior) via the command-line + option to ecpg (see below) or via the EXEC SQL SET AUTOCOMMIT TO ON statement. In autocommit mode, each command is automatically committed unless it is inside an explicit transaction block. This mode can be explicitly turned off using @@ -448,7 +448,7 @@ char foo[16], bar[16]; The declarations are also echoed to the output file as a normal C variables, so there's no need to declare them again. Variables - that are not intended to be used with SQL commands can be declared + that are not intended to be used in SQL commands can be declared normally outside these special sections. @@ -553,7 +553,7 @@ do { second host variable specification to each host variable that contains data. This second host variable is called the indicator and contains a flag that tells - whether the datums is null, in which case the value of the real + whether the datum is null, in which case the value of the real host variable is ignored. Here is an example that handles the retrieval of null values correctly: @@ -1043,7 +1043,7 @@ static void set_error_handler(void) sqlca - For a more powerful error handling, the embedded SQL interface + For more powerful error handling, the embedded SQL interface provides a global variable with the name sqlca that has the following structure: @@ -1064,7 +1064,7 @@ struct } sqlca; (In a multithreaded program, every thread automatically gets its - own copy of sqlca. This works similar to the + own copy of sqlca. This works similarly to the handling of the standard C global variable errno.) @@ -1132,7 +1132,7 @@ struct The structure sqlca is not defined in the SQL standard, but is implemented in several other SQL database - systems. The definitions are similar in the core, but if you want + systems. The definitions are similar at the core, but if you want to write portable applications, then you should investigate the different implementations carefully. @@ -1539,7 +1539,7 @@ ecpg prog1.pgc cc -c prog1.c - The generated C source files include headers files from the + The generated C source files include header files from the PostgreSQL installation, so if you installed PostgreSQL in a location that is not searched by default, you have to add an option such as @@ -1575,9 +1575,9 @@ ECPG = ecpg - ecpg is thread-safe if it is compiled using - the @@ -1621,7 +1621,7 @@ ECPG = ecpg Internals - This section explain how ECPG works + This section explains how ECPG works internally. This information can occasionally be useful to help users understand how to use ECPG. diff --git a/doc/src/sgml/external-projects.sgml b/doc/src/sgml/external-projects.sgml index bcef777329..5e52fd01b6 100644 --- a/doc/src/sgml/external-projects.sgml +++ b/doc/src/sgml/external-projects.sgml @@ -1,5 +1,5 @@ @@ -9,15 +9,28 @@ $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.5 2004/12/13 18:05:08 PostgreSQL is a complex software project, and managing it is difficult. We have found that many enhancements to PostgreSQL can be more - efficiently developed independently of the main project. They can - have their own developer teams, email lists, their own bug tracking, - and their own release schedule. While their independence makes - development easier, it makes user's jobs harder. They have to hunt + efficiently developed separately from the core project. Separate + projects can + have their own developer teams, email lists, bug tracking, + and release schedules. While their independence makes + development easier, it makes users' jobs harder. They have to hunt around looking for database enhancements to meet their needs. - This section outlines some of the more popular externally + This section describes some of the more popular externally developed enhancements and guides you on how to find them. + + Many PostgreSQL-related projects are + hosted at either + GBorg at + http://gborg.postgresql.org or + pgFoundry at http://pgfoundry.org. + There are other + PostgreSQL-related projects that are hosted + elsewhere, but you will have to do an Internet search to find them. + + Externally Developed Interfaces @@ -36,11 +49,7 @@ $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.5 2004/12/13 18:05:08 - To use other interfaces, you have to do some searching. For example, - GBorg at - http://gborg.postgresql.org has over thirty interfaces listed - in its Drivers/Interfaces section. Some of the more - popular interfaces are: + Some of the more popular interfaces are: @@ -53,6 +62,15 @@ $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.5 2004/12/13 18:05:08 + + pgjdbc + + + A JDBC interface. + + + + Npgsql @@ -64,19 +82,19 @@ $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.5 2004/12/13 18:05:08 - libpq++ + libpqxx - An older C++ interface. + A newer C++ interface. - libpqxx + libpq++ - A newer C++ interface. + An older C++ interface. @@ -101,11 +119,20 @@ $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.5 2004/12/13 18:05:08 + + pgtclng + + + A newer version of the Tcl interface. + + + + pgtcl - The original version of the TCL interface. + The original version of the Tcl interface. @@ -119,35 +146,9 @@ $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.5 2004/12/13 18:05:08 - - pgjdbc - - - A JDBC interface. - - - - - - pgtclng - - - A newer version of the TCL interface. - - - - - - That section also contains several server-side languages that are - separate projects. pgFoundry at http://pgfoundry.org contains - even more projects. Other projects are not even hosted on these - servers and you will have to do an Internet search to find them. - - @@ -169,7 +170,7 @@ $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.5 2004/12/13 18:05:08 like PostGIS. Even PostgreSQL replication solutions are developed externally. For example, Slony-I is a popular master/slave replication solution - that is developed independently from the main projects. + that is developed independently from the core project. diff --git a/doc/src/sgml/information_schema.sgml b/doc/src/sgml/information_schema.sgml index b617d014e9..18cae62998 100644 --- a/doc/src/sgml/information_schema.sgml +++ b/doc/src/sgml/information_schema.sgml @@ -1,4 +1,4 @@ - + The Information Schema @@ -30,7 +30,7 @@ exists in all databases. The owner of this schema is the initial database user in the cluster, and that user naturally has all the privileges on this schema, including the ability to drop it (but - the space savings achieved by this are minuscule). + the space savings achieved by that are minuscule). @@ -1003,7 +1003,7 @@ function (as parameter or return type) and stores some information about how the data type is used in that instance (for example, the declared maximum length, if applicable). Each data type - descriptors is assigned an arbitrary identifier that is unique + descriptor is assigned an arbitrary identifier that is unique among the data type descriptor identifiers assigned for one object (table, domain, function). This view is probably not useful for applications, but it is used to define some other views in the @@ -1735,7 +1735,7 @@ ORDER BY c.ordinal_position; in the current database that are restricted by some unique, primary key, or foreign key constraint. Check constraints are not included in this view. Only those columns are shown that are contained in a - table owned the current user. + table owned by the current user. @@ -3320,7 +3320,7 @@ ORDER BY c.ordinal_position; The table sql_packages contains information - about which features packages defined in the SQL standard are + about which feature packages defined in the SQL standard are supported by PostgreSQL. Refer to for background information on feature packages. @@ -3888,7 +3888,7 @@ ORDER BY c.ordinal_position; incompatibilities with the SQL standard that affect the representation in the information schema. First, trigger names are local to the table in PostgreSQL, rather - than independent schema objects. Therefore there may be duplicate + than being independent schema objects. Therefore there may be duplicate trigger names defined in one schema, as long as they belong to different tables. (trigger_catalog and trigger_schema are really the values pertaining diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index ef4df84918..b355e303ca 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,5 +1,5 @@ @@ -19,11 +19,19 @@ $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.172 2004/12/20 18:15:05 tgl Exp $ libpq is a set of library functions that allow client programs to pass queries to the PostgreSQL backend server and to receive the results of these queries. + + + libpq is also the underlying engine for several other PostgreSQL application interfaces, including - those written for C++, TCL, Perl, Python and ECPG. + those written for C++, Perl, Python, Tcl and ECPG. So some aspects of libpq's behavior will be - important to you if you use one of those packages. + important to you if you use one of those packages. In particular, + , + and + + describe behavior that is visible to the user of any application + that uses libpq. @@ -49,7 +57,7 @@ $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.172 2004/12/20 18:15:05 tgl Exp $ application program can have several backend connections open at one time. (One reason to do that is to access more than one database.) Each connection is represented by a - PGconnPGconn object which + PGconnPGconn object, which is obtained from the function PQconnectdb or PQsetdbLogin. Note that these functions will always return a non-null object pointer, unless perhaps there is too @@ -82,12 +90,12 @@ PGconn *PQconnectdb(const char *conninfo); can be empty to use all default parameters, or it can contain one or more parameter settings separated by whitespace. Each parameter setting is in the form keyword = value. - (To write an empty value or a value containing + Spaces around the equal sign are optional. + To write an empty value or a value containing spaces, surround it with single quotes, e.g., keyword = 'a value'. Single quotes and backslashes within the value must be escaped with a - backslash, i.e., \' and \\.) - Spaces around the equal sign are optional. + backslash, i.e., \' and \\. @@ -172,6 +180,8 @@ PGconn *PQconnectdb(const char *conninfo); PostgreSQL user name to connect as. + Defaults to be the same as the operating system name of the user + running the application. @@ -235,7 +245,7 @@ PGconn *PQconnectdb(const char *conninfo); If PostgreSQL is compiled without SSL support, using option require will cause an error, while options allow and prefer will be - tolerated but libpq will be unable to negotiate + accepted but libpq will not in fact attempt an SSL connection.SSLwith libpq @@ -273,8 +283,8 @@ PGconn *PQconnectdb(const char *conninfo); name in pg_service.conf that holds additional connection parameters. This allows applications to specify only a service name so connection parameters can be centrally maintained. See - PREFIX/share/pg_service.conf.sample for - information on how to set up the file. + share/pg_service.conf.sample in the installation + directory for information on how to set up the file. @@ -283,7 +293,7 @@ PGconn *PQconnectdb(const char *conninfo); If any parameter is unspecified, then the corresponding environment variable (see ) is checked. If the environment variable is not set either, - then built-in defaults are used. + then the indicated built-in defaults are used. @@ -489,7 +499,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); Note that, although these constants will remain (in order to maintain - compatibility), an application should never rely upon these appearing in a + compatibility), an application should never rely upon these occurring in a particular order, or at all, or on the status always being one of these documented values. An application might do something like this: @@ -877,7 +887,8 @@ Pre-3.0-protocol servers do not report parameter settings, but libpq includes logic to obtain values for server_version and client_encoding anyway. Applications are encouraged to use PQparameterStatus -rather than ad-hoc code to determine these values. (Beware however +rather than ad hoc code to determine these values. +(Beware however that on a pre-3.0 connection, changing client_encoding via SET after connection startup will not be reflected by PQparameterStatus.) For server_version, @@ -905,8 +916,8 @@ Applications may wish to use this to determine whether certain features are supported. Currently, the possible values are 2 (2.0 protocol), 3 (3.0 protocol), or zero (connection bad). This will not change after connection -startup is complete, but it could theoretically change during a reset. -The 3.0 protocol will normally be used when communicating with +startup is complete, but it could theoretically change during a connection +reset. The 3.0 protocol will normally be used when communicating with PostgreSQL 7.4 or later servers; pre-7.4 servers support only protocol 2.0. (Protocol 1.0 is obsolete and not supported by libpq.) @@ -950,7 +961,9 @@ char *PQerrorMessage(const PGconn *conn); PQerrorMessage result will include a trailing newline. The caller should not free the result directly. It will be freed when the associated PGconn - handle is passed to PQfinish. + handle is passed to PQfinish. The result string + should not be expected to remain the same across operations on the + PGconn structure. @@ -1014,7 +1027,7 @@ SSL *PQgetssl(const PGconn *conn); You must define USE_SSL in order to get the - prototype for this function. Doing this will also + correct prototype for this function. Doing this will also automatically include ssl.h from OpenSSL. @@ -1768,7 +1781,8 @@ exactly which table is referenced. Returns the column number (within its table) of the column making up the specified query result column. - Result column numbers start at 0. + Query-result column numbers start at 0, but table columns have nonzero + numbers. int PQftablecol(const PGresult *res, int column_number); @@ -2678,7 +2692,7 @@ server, using the functions described in this section. Creates a data structure containing the information needed to cancel - a command issued through a particular database connection. + a command issued through a particular database connection. PGcancel *PQgetCancel(PGconn *conn); @@ -3614,8 +3628,9 @@ information into simple client applications, for example. PGHOST sets the database server name. If this begins with a slash, it specifies Unix-domain communication -rather than TCP/IP communication; the value is the name of the -directory in which the socket file is stored (default /tmp). +rather than TCP/IP communication; the value is then the name of the +directory in which the socket file is stored (in a default installation +setup this would be /tmp). @@ -3624,8 +3639,8 @@ directory in which the socket file is stored (default /tmp) PGHOSTADDR PGHOSTADDR specifies the numeric IP address of the database -server. This can be set instead of PGHOST to avoid DNS -lookup overhead. See the documentation of +server. This can be set instead of or in addition to PGHOST +to avoid DNS lookup overhead. See the documentation of these parameters, under PQconnectdb above, for details on their interaction. @@ -3666,7 +3681,7 @@ sets the user name used to connect to the database. PGPASSWORD sets the password used if the server demands password authentication. This environment variable is deprecated for security -reasons; consider migrating to use the $HOME/.pgpass +reasons; instead consider using the $HOME/.pgpass file (see ). @@ -3718,9 +3733,9 @@ trying an SSL connection; prefer connection, then if that fails, trying a regular non-SSL connection; require will try only an SSL connection. If PostgreSQL is compiled without SSL support, -using option require will cause an error, and options -allow and prefer will be tolerated but -libpq will be unable to negotiate an SSL +using option require will cause an error, while options +allow and prefer will be accepted but +libpq will not in fact attempt an SSL connection. @@ -3758,7 +3773,9 @@ It is not recommended to set the timeout to less than 2 seconds. The following environment variables can be used to specify default behavior for each PostgreSQL session. -(See also the ALTER USER and ALTER DATABASE +(See also the + and + commands for ways to set default behavior on a per-user or per-database basis.) @@ -3803,6 +3820,18 @@ sets the default mode for the genetic query optimizer. (Equivalent to SET geqo TO ....) + + +Refer to the SQL command + +for information on correct values for these environment variables. + + + +The following environment variables determine internal behavior of +libpq; they override compiled-in defaults. + + @@ -3818,13 +3847,11 @@ sets the directory containing the pg_service.conf file. PGLOCALEDIR PGLOCALEDIR -sets the directory containing the locale files. +sets the directory containing the locale files for message +internationalization. - -Refer to the SQL command SET -for information on correct values for these environment variables. @@ -3910,7 +3937,7 @@ If the permissions are less strict than this, the file will be ignored. libpq is reentrant and thread-safe if the configure command-line option ---enable-thread-safety has been used when the +--enable-thread-safety was 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 @@ -3974,7 +4001,8 @@ your library might not match the library used to build the binaries. - To build (i.e., compile and link) your libpq programs you need to + To build (i.e., compile and link) a program using + libpq you need to do all of the following things: diff --git a/doc/src/sgml/lobj.sgml b/doc/src/sgml/lobj.sgml index 3520b808b9..d2b7b06f57 100644 --- a/doc/src/sgml/lobj.sgml +++ b/doc/src/sgml/lobj.sgml @@ -1,5 +1,5 @@ @@ -9,15 +9,11 @@ $PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.33 2003/11/29 19:51:37 pgsql Exp $ BLOBlarge object - In PostgreSQL releases prior to 7.1, - the size of any row in the database could not exceed the size of a - data page. Since the size of a data page is 8192 bytes (the - default, which can be raised up to 32768), the upper limit on the - size of a data value was relatively low. To support the storage of - larger atomic values, PostgreSQL - provided and continues to provide a large object interface. This - interface provides file-oriented access to user data that is stored in - a special large-object structure. + PostgreSQL has a large object + facility, which provides stream-style access to user data that is stored + in a special large-object structure. Streaming access is useful + when working with data values that are too large to manipulate + conveniently as a whole. @@ -59,10 +55,13 @@ $PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.33 2003/11/29 19:51:37 pgsql Exp $ sliced breadTOAST PostgreSQL 7.1 introduced a mechanism (nicknamed TOAST) that allows - data rows to be much larger than individual data pages. This - makes the large object interface partially obsolete. One - remaining advantage of the large object interface is that it allows values up - to 2 GB in size, whereas TOAST can only handle 1 GB. + data values to be much larger than single pages. This + makes the large object facility partially obsolete. One + remaining advantage of the large object facility is that it allows values + up to 2 GB in size, whereas TOASTed fields can be at + most 1 GB. Also, large objects can be manipulated piece-by-piece much more + easily than ordinary data fields, so the practical limits are considerably + different. @@ -117,7 +116,7 @@ Oid lo_creat(PGconn *conn, int mode); creates a new large object. mode is a bit mask describing several different attributes of the new - object. The symbolic constants listed here are defined + object. The symbolic constants used here are defined in the header file libpq/libpq-fs.h. The access type (read, write, or both) is controlled by or'ing together the bits INV_READ and @@ -149,6 +148,9 @@ Oid lo_import(PGconn *conn, const char *filename); specifies the operating system name of the file to be imported as a large object. The return value is the OID that was assigned to the new large object. + Note that the file is read by the client interface library, not by + the server; so it must exist in the client filesystem and be readable + by the client application. @@ -164,7 +166,9 @@ int lo_export(PGconn *conn, Oid lobjId, const char *filename); lo_export The lobjId argument specifies the OID of the large object to export and the filename argument specifies - the operating system name name of the file. + the operating system name of the file. + Note that the file is written by the client interface library, not by + the server. @@ -200,7 +204,7 @@ int lo_write(PGconn *conn, int fd, const char *buf, size_t len); lo_write writes len bytes from buf - to large object fd. The fd + to large object descriptor fd. The fd argument must have been returned by a previous lo_open. The number of bytes actually written is returned. In the event of an error, the return value @@ -217,7 +221,7 @@ int lo_write(PGconn *conn, int fd, const char *buf, size_t len); int lo_read(PGconn *conn, int fd, char *buf, size_t len); lo_read reads - len bytes from large object + len bytes from large object descriptor fd into buf. The fd argument must have been returned by a previous lo_open. The number of bytes @@ -227,16 +231,16 @@ int lo_read(PGconn *conn, int fd, char *buf, size_t len); -Seeking on a Large Object +Seeking in a Large Object - To change the current read or write location on a large - object, call + To change the current read or write location associated with a + large object descriptor, call int lo_lseek(PGconn *conn, int fd, int offset, int whence); lo_lseek This function moves the - current location pointer for the large object described by + current location pointer for the large object descriptor identified by fd to the new location specified by offset. The valid values for whence are SEEK_SET (seek from object start), @@ -250,7 +254,7 @@ int lo_lseek(PGconn *conn, int fd, int offset, int whence); Obtaining the Seek Position of a Large Object - To obtain the current read or write location of a large object, + To obtain the current read or write location of a large object descriptor, call int lo_tell(PGconn *conn, int fd); @@ -264,7 +268,7 @@ int lo_tell(PGconn *conn, int fd); Closing a Large Object Descriptor - A large object may be closed by calling + A large object descriptor may be closed by calling int lo_close(PGconn *conn, int fd);