From: Thomas G. Lockhart Date: Tue, 29 Dec 1998 02:24:47 +0000 (+0000) Subject: Clean up to ensure tag completion as required by the newest versions X-Git-Tag: REL6_5~860 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=a75f2d21a8366aece67b8aa144a8644f6195e75f;p=postgresql Clean up to ensure tag completion as required by the newest versions of Norm's Modular Style Sheets and jade/docbook. From Vince Vielhaber . --- diff --git a/doc/src/sgml/about.sgml b/doc/src/sgml/about.sgml index ebdb125809..5f43906a13 100644 --- a/doc/src/sgml/about.sgml +++ b/doc/src/sgml/about.sgml @@ -4,15 +4,15 @@ PostgreSQL is available without cost. This manual describes version 6.4 of PostgreSQL. - + We will use Postgres to mean the version distributed as PostgreSQL. - + Check the Administrator's Guide for a list of currently supported machines. In general, Postgres is portable to any Unix/Posix-compatible system with full libc library support. - + diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml index f0709c3ea8..245c90f5a9 100644 --- a/doc/src/sgml/advanced.sgml +++ b/doc/src/sgml/advanced.sgml @@ -66,6 +66,7 @@ SELECT name, altitude |Mariposa | 1953 | +----------+----------+ + On the other hand, to find the names of all cities, @@ -111,6 +112,7 @@ SELECT c.name, c.altitude sub-values that can be accessed from the query language. For example, you can create attributes that are arrays of base types. + Arrays @@ -210,7 +212,7 @@ SELECT SAL_EMP.schedule[1:2][1:1] +-------------------+ - + @@ -286,6 +288,7 @@ On UNIX systems, this is always midnight, January 1, 1970 GMT. |Mariposa | 1320 | +---------+------------+ + The default beginning of a time range is the earliest @@ -293,6 +296,7 @@ On UNIX systems, this is always midnight, January 1, 1970 GMT. the current time; thus, the above time range can be abbreviated as ``[,].'' + More Advanced Features @@ -301,5 +305,7 @@ On UNIX systems, this is always midnight, January 1, 1970 GMT. Postgres has many features not touched upon in this tutorial introduction, which has been oriented toward newer users of SQL. These are discussed in more detail in both the User's and Programmer's Guides. + + diff --git a/doc/src/sgml/arch-dev.sgml b/doc/src/sgml/arch-dev.sgml index 217ed9574b..076952eb60 100644 --- a/doc/src/sgml/arch-dev.sgml +++ b/doc/src/sgml/arch-dev.sgml @@ -30,6 +30,7 @@ + A single postmaster manages a given collection of @@ -76,5 +77,5 @@ case, all files relating to a database should belong to this Postgres superuser. - + diff --git a/doc/src/sgml/arch-pg.sgml b/doc/src/sgml/arch-pg.sgml index 3b03811418..5155f02d4f 100644 --- a/doc/src/sgml/arch-pg.sgml +++ b/doc/src/sgml/arch-pg.sgml @@ -30,7 +30,7 @@ - + A single postmaster manages a given collection of databases on a single host. Such a collection of @@ -79,5 +79,5 @@ Furthermore, the Postgres superuser should case, all files relating to a database should belong to this Postgres superuser. - + diff --git a/doc/src/sgml/arch.sgml b/doc/src/sgml/arch.sgml index aeb53207c0..96df1f3c03 100644 --- a/doc/src/sgml/arch.sgml +++ b/doc/src/sgml/arch.sgml @@ -12,6 +12,7 @@ In database jargon, Postgres uses a simple "process per-user" client/server model. A Postgres session consists of the following cooperating UNIX processes (programs): + @@ -53,6 +54,7 @@ postmaster. Hence, the postmaster is always running, waiting for requests, whereas frontend and backend processes come and go. + The libpq library allows a single @@ -69,6 +71,7 @@ machine may not be accessible (or may only be accessed using a different filename) on the database server machine. + You should also be aware that the postmaster and @@ -81,5 +84,5 @@ case, all files relating to a database should belong to this Postgres superuser. - + diff --git a/doc/src/sgml/bki.sgml b/doc/src/sgml/bki.sgml index 0923b57c67..4a61fd6d6b 100644 --- a/doc/src/sgml/bki.sgml +++ b/doc/src/sgml/bki.sgml @@ -1,5 +1,5 @@ + Documentation Files @@ -482,6 +515,8 @@ Status + + Document Conversion @@ -719,7 +754,8 @@ Status - + + Styles and Conventions @@ -766,6 +802,7 @@ be included below. --> + SGML Authoring Tools @@ -774,12 +811,14 @@ be included below. The current Postgres documentation set was written using a plain text editor (or emacs/psgml; see below) with the content marked up using SGML DocBook tags. + SGML and DocBook do not suffer from an oversupply of open-source authoring tools. The most common toolset is the emacs/xemacs editing package with the psgml feature extension. On some systems (e.g. RedHat Linux) these tools are provided in a typical full installation. + emacs/psgml @@ -789,6 +828,7 @@ On some systems (e.g. RedHat Linux) these tools are provided in a typical full i an SGML major mode. When properly configured, this will allow you to use emacs to insert tags and check markup consistancy. + Put the following in your ~/.emacs environment file: @@ -832,13 +872,15 @@ sgml-exposed-tags:nil sgml-local-catalogs:"/usr/lib/sgml/catalog" sgml-local-ecat-files:nil End: --- +-- + The Postgres distribution includes a parsed DTD definitions file reference.ced. You may find that + When using emacs/psgml, a comfortable way of working with @@ -853,6 +895,7 @@ a DocBook document by making the first line look like this: This means that anything and everything that reads SGML will get it right, and I can verify the document with "nsgmls -s docguide.sgml". + @@ -893,6 +936,7 @@ On many systems, these stylesheets will be found in packages installed in /usr/share/lib/sgml/, or /usr/local/lib/sgml/. + HTML documentation packages can be generated from the SGML source by @@ -926,6 +970,7 @@ The hardcopy Postscript documentation is generated by converting the importing into ApplixWare-4.4.1. After a little cleanup (see the following section) the output is "printed" to a postscript file. + Some figures were redrawn to avoid having bitmap @@ -1066,6 +1111,7 @@ We understand that there are some other packaged distributions for these tools. FreeBSD seems to have them available. Please report package status to the docs mailing list and we will include that information here. + <acronym>RPM</acronym> installation on @@ -1086,6 +1132,7 @@ This is a brief run-through of the process of obtaining and installing the software you'll need to edit DocBook source with Emacs and process it with Norman Walsh's DSSSL style sheets to create <acronym>HTML</acronym> and <acronym>RTF</acronym>. +</para> <para> These instructions do not cover new <application>jade</application>/DocBook @@ -1093,6 +1140,7 @@ support in the <ulink url="http://www.sgmltools.org/"><productname>sgml-tools</productname></ulink> package. The authors have not tried this package since it adopted DocBook, but it is almost certainly a good candidate for use. +</para> <sect3><title>Prerequisites @@ -1150,12 +1198,12 @@ Steve Pepper's Whirlwind Guide Robin Cover's database of SGML software + Installing Jade - Installing Jade @@ -1164,6 +1212,8 @@ Robin Cover's database of SGML software Read the installation instructions at the above listed URL. + + @@ -1173,6 +1223,7 @@ this will be something like unzip -aU jade1_1.zip + Jade is not built using @@ -1215,21 +1266,23 @@ doesn't need the above settings for the math library and the ranlib command, leave them as they are in the Makefile. + Type make to build Jade and the various SP tools. + Once the software is built, make install will do the obvious. - + + Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit - Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit @@ -1255,6 +1308,8 @@ the former, by giving it the single line of content: CATALOG /usr/local/share/sgml/CATALOG + + @@ -1274,6 +1329,8 @@ PUBLIC "-//Davenport//ELEMENTS DocBook Information Pool V3.0//EN" dbpool.mod PUBLIC "-//Davenport//ELEMENTS DocBook Document Hierarchy V3.0//EN" dbhier.mod PUBLIC "-//Davenport//ENTITIES DocBook Additional General Entities V3.0//EN" dbgenent.mod + + @@ -1296,12 +1353,13 @@ we've placed the ISO entity files in a subdirectory named ISO. Again, proper catalog entries should accompany the entity kit you fetch. + + Installing Norman Walsh's <acronym>DSSSL</acronym> Style Sheets - Installing Norman Walsh's <acronym>DSSSL</acronym> Style Sheets @@ -1309,6 +1367,7 @@ accompany the entity kit you fetch. Read the installation instructions at the above listed URL. + To install Norman's style sheets, simply unzip the distribution @@ -1320,11 +1379,13 @@ The command will be something like unzip -aU db119.zip + One way to test the installation is to build the HTML and RTF forms of the PostgreSQL User's Guide. + @@ -1336,9 +1397,12 @@ directory, doc/src/sgml, and say jade -t sgml -d /usr/local/share/docbook/html/docbook.dsl -D ../graphics postgres.sgml + book1.htm is the top level node of the output.. + + @@ -1347,14 +1411,17 @@ into your favorite word processing system and printing, type: jade -t rtf -d /usr/local/share/docbook/print/docbook.dsl -D ../graphics postgres.sgml + + + + Installing <productname>PSGML</productname> - Installing <productname>PSGML</productname> @@ -1362,10 +1429,13 @@ jade -t rtf -d /usr/local/share/docbook/print/docbook.dsl -D ../graphics postgre Read the installation instructions at the above listed URL. + Unpack the distribution file, run configure, make and make install to put the byte-compiled files and info library in place. + + @@ -1378,6 +1448,8 @@ file to make Emacs properly load (cons "/usr/local/share/emacs/site-lisp/psgml" load-path)) (autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t) + + @@ -1388,7 +1460,7 @@ If you want to use PSGML when editing (cons '("\\.s?html?\\'" . sgml-mode) auto-mode-alist)) - + There is one important thing to note with @@ -1397,18 +1469,23 @@ If you want to use PSGML when editing /usr/local/lib/sgml. If, as in the examples in this chapter, you use /usr/local/share/sgml, you have to compensate for this. + You can set the SGML_CATALOG_FILES environment variable. + + You can customize your PSGML installation (its manual tells you how). + + @@ -1416,10 +1493,13 @@ You can even edit the source file psgml.el before compiling and installing PSGML, changing the hard-coded paths to match your own default. + + + Installing <productname>JadeTeX</productname> @@ -1503,6 +1583,7 @@ now supports jade and DocBook. It may be the preferred toolset for working with SGML but we have not had a chance to evaluate the new package. + - + + + Unix Installation @@ -152,6 +169,7 @@ supported on at least some platforms. demonstrated under Linux with Postgres v6.4 using the psqlODBC driver contained in the Postgres distribution. + Building the Driver @@ -171,11 +189,13 @@ Instructions for installing iodbc document, but there is a README that can be found inside the iodbc compressed .shar file that should explain how to get it up and running. + Having said that, any driver manager that you can find for your platform should support the psqlODBC driver or any ODBC driver. + The Unix configuration files for psqlODBC @@ -187,6 +207,7 @@ a simple process to build the driver on the supported platforms. Currently these include Linux and FreeBSD but we are hoping other users will contribute the necessary information to quickly expand the number of platforms for which the driver can be built. + There are actually two separate methods to build the driver depending on @@ -198,6 +219,7 @@ The standalone installation is convenient if you have ODBC client applications on multiple, heterogeneous platforms. The integrated installation is convenient when the target client is the same as the server, or when the client and server have similar runtime configurations. + Specifically if you have received the psqlODBC @@ -210,12 +232,14 @@ of the Postgres distribution If you received the driver as a standalone package than you will run configure and make from the directory in which you unpacked the driver source. + Integrated Installation This installation procedure is appropriate for an integrated installation. + @@ -226,7 +250,8 @@ command-line argument for src/configure: % ./configure --with-odbc % make - + + Rebuild the Postgres distribution: @@ -234,7 +259,8 @@ Rebuild the Postgres distribution: % make install - + + @@ -248,6 +274,7 @@ as % make ODBCINST=filename install + Pre-v6.4 Integrated Installation @@ -257,12 +284,14 @@ If you have a Postgres installation older than v6.4, you have the original source tree available, and you want to use the newest version of the ODBC driver, then you may want to try this form of installation. + Copy the output tar file to your target system and unpack it into a clean directory. - + + From the directory containing the @@ -273,6 +302,8 @@ sources, type: % make % make POSTGRESDIR=PostgresTopDir install + + @@ -282,7 +313,8 @@ then you can specify various destinations explicitly: % make BINDIR=bindir LIBDIR=libdir HEADERDIR=headerdir ODBCINST=instfile install - + + @@ -294,6 +326,7 @@ A standalone installation is not integrated with or built on the normal for building the ODBC driver for multiple, heterogeneous clients who do not have a locally-installed Postgres source tree. + The default location for libraries and headers @@ -303,6 +336,7 @@ There is another system wide configuration file that gets installed as /share/odbcinst.ini (if /share exists) or as /etc/odbcinst.ini (if /share does not exist). + @@ -312,6 +346,7 @@ Most installation steps for Postgres do not have this requirement, and you can choose another destination which is writable by your non-root Postgres superuser account instead. + @@ -320,6 +355,7 @@ The standalone installation distribution can be built from the Postgres distribution or may be obtained from Insight Distributors, the current maintainers of the non-Unix sources. + Copy the zip @@ -332,6 +368,7 @@ unzip it with the command The option is necessary to get rid of DOS CR/LF pairs in the source files. + If you have the gzipped tar package than simply run @@ -339,6 +376,7 @@ If you have the gzipped tar package than simply run tar -xzf packagename + @@ -346,13 +384,15 @@ tar -xzf packagename To create a tar file for a complete standalone installation from the main Postgres source tree: - + + - + Configure the main Postgres distribution. - + + Create the tar file: @@ -361,16 +401,22 @@ Create the tar file: % cd interfaces/odbc % make standalone + + Copy the output tar file to your target system. Be sure to transfer as a binary file if using ftp. + + Unpack the tar file into a clean directory. + + @@ -379,6 +425,7 @@ Configure the standalone installation: % ./configure + The configuration can be done with options: @@ -392,6 +439,7 @@ the directories rootdir/lib and rootdir/include/iodbc, and installs odbcinst.ini in the specified directory. + Note that both of these options can also be used from the integrated build @@ -400,6 +448,8 @@ but be aware that when used in the integrated build your Postgres installation. applies only to the configuration file odbcinst.ini. + + @@ -408,6 +458,7 @@ Compile and link the source code: % make ODBCINST=instdir + You can also override the default location for installation on the @@ -418,6 +469,8 @@ that specifies its installation directory will probably cause you headaches. It is safest simply to allow the driver to install the odbcinst.ini file in the default directory or the directory you specified on the './configure' command line with --with-odbc. + + diff --git a/doc/src/sgml/oper.sgml b/doc/src/sgml/oper.sgml index 2c865ba905..f57e981a76 100644 --- a/doc/src/sgml/oper.sgml +++ b/doc/src/sgml/oper.sgml @@ -15,6 +15,7 @@ These operators are declared in the system catalog pg_operator. Every entry in pg_operator includes the name of the procedure that implements the operator and the class OIDs of the input and output types. + To view all variations of the || string concatenation operator, @@ -45,11 +46,12 @@ as: select * from emp where int4lt(salary, 40000); + psql has a command (\dd) to show these operators. - + Lexical Precedence @@ -70,180 +72,255 @@ Operator Ordering (decreasing precedence) Element + Precedence + Description + + UNION + left + SQL select construct + + :: + + Postgres typecasting - + + [ ] + left + array delimiters - + + . + left + table/column delimiter - + + - + right + unary minus - + + ; + left + statement termination, logarithm - + + : + right + exponentiation - + + | + left + start of interval - + + * / + left + multiplication, division - + + + - + left + addition, subtraction - + + IS + + test for TRUE, FALSE, NULL + + ISNULL + + test for NULL - + + NOTNULL + + test for NOT NULL - + + (all other operators) + + native and user-defined - + + IN + + set membership - + + BETWEEN + + containment - + + LIKE + + string pattern matching - + + < > + + boolean inequality - + + = + right + equality - + + NOT + right + negation - + + AND + left + logical intersection - + + OR + left + logical union - + + + + + General Operators @@ -251,7 +328,7 @@ logical union The operators listed here are defined for a number of native data types, ranging from numeric types to data/time types. - + <ProductName>Postgres</ProductName> Operators @@ -339,6 +416,7 @@ ranging from numeric types to data/time types.
+ Numerical Operators @@ -430,6 +508,7 @@ ranging from numeric types to data/time types. + Geometric Operators @@ -571,6 +650,7 @@ ranging from numeric types to data/time types. + Time Interval Operators @@ -651,6 +731,7 @@ are several operators for this type. + IP V4 Operators diff --git a/doc/src/sgml/page.sgml b/doc/src/sgml/page.sgml index 8c468ca3b1..0e93f3e4c7 100644 --- a/doc/src/sgml/page.sgml +++ b/doc/src/sgml/page.sgml @@ -11,6 +11,7 @@ A description of the database file default page format. This section provides an overview of the page format used by Postgres classes. User-defined access methods need not use this page format. + In the following explanation, a @@ -18,6 +19,7 @@ In the following explanation, a is assumed to contain 8 bits. In addition, the term item refers to data which is stored in Postgres classes. + Page Structure @@ -41,50 +43,73 @@ Description + + itemPointerData + + filler + + itemData... + + Unallocated Space + + ItemContinuationData + + Special Space + + ``ItemData 2'' + + ``ItemData 1'' + + ItemIdData + + PageHeaderData + + + next-internal-state1 -sfunc2( internal-state2 ) ---> next-internal-state2 - + sfunc1 + and sfunc2: + + sfunc1( internal-state1, next-data_item ) ---> next-internal-state1 + sfunc2( internal-state2 ) ---> next-internal-state2 + and a final calculation function, - ffunc: - -ffunc(internal-state1, internal-state2) ---> aggregate-value - - - -Postgres creates up to two temporary variables -(referred to here as temp1 -and temp2) -to hold intermediate results used as arguments to the transition functions. - - + ffunc: + + ffunc(internal-state1, internal-state2) ---> aggregate-value + + + + Postgres creates up to two temporary variables + (referred to here as temp1 + and temp2) + to hold intermediate results used as arguments to the transition functions. + + These transition functions are required to have the following properties: The arguments to -sfunc1 - must be -temp1 -of type -sfunc1_return_type -and -column_value -of type data_type. -The return value must be of type -sfunc1_return_type -and will be used as the first argument in the next call to -sfunc1. + sfunc1 + must be + temp1 + of type + sfunc1_return_type + and + column_value + of type data_type. + The return value must be of type + sfunc1_return_type + and will be used as the first argument in the next call to + sfunc1. - + The argument and return value of -sfunc2 -must be -temp2 -of type -sfunc2_return_type. + sfunc2 + must be + temp2 + of type + sfunc2_return_type. The arguments to the final-calculation-function must be -temp1 -and -temp2 -and its return value must + temp1 + and + temp2 + and its return value must be a Postgres - base type (not necessarily - data_type -which had been specified for BASETYPE). + base type (not necessarily + data_type + which had been specified for BASETYPE). @@ -269,7 +273,7 @@ which had been specified for BASETYPE). - + An aggregate function may also require one or two initial conditions, one for @@ -301,41 +305,42 @@ which had been specified for BASETYPE). well as a FINALFUNC (a division function) to produce its answer. In any case, at least one state function must be defined, and any SFUNC2 must have a corresponding INITCOND2. - - + + - + + Usage -Refer to the chapter on aggregate functions - in the PostgreSQL Programmer's Guide - on aggregate functions for -complete examples of usage. - + Refer to the chapter on aggregate functions + in the PostgreSQL Programmer's Guide + on aggregate functions for + complete examples of usage. + Compatibility - - + -1998-09-09 + 1998-09-09 SQL92 CREATE AGGREGATE -is a Postgres language extension. + is a Postgres language extension. There is no CREATE AGGREGATE in SQL92. - + + + + Release v1.01 @@ -1270,32 +1334,34 @@ Fri Feb 23 18:20:36 PST 1996 The following notes are for the benefit of users who want to migrate databases from postgres95 1.0 to postgres95 1.01. - + If you are starting afresh with postgres95 1.01 and do not need to migrate old databases, you do not need to read any further. - + In order to postgres95 version 1.01 with databases created with postgres95 version 1.0, the following steps are required: - + Set the definition of NAMEDATALEN in src/Makefile.global to 16 and OIDNAMELEN to 20. - + + Decide whether you want to use Host based authentication. - + If you do, you must create a file name "pg_hba" in your top-level data directory (typically the value of your $PGDATA). src/libpq/pg_hba shows an example syntax. - + + If you do not want host-based authentication, you can comment out @@ -1304,35 +1370,43 @@ If you do not want host-based authentication, you can comment out HBA = 1 in src/Makefile.global - + Note that host-based authentication is turned on by default, and if you do not take steps A or B above, the out-of-the-box 1.01 will not allow you to connect to 1.0 databases. + + + Compile and install 1.01, but DO NOT do the initdb step. - + + Before doing anything else, terminate your 1.0 postmaster, and backup your existing $PGDATA directory. - + + Set your PGDATA environment variable to your 1.0 databases, but set up path up so that 1.01 binaries are being used. - + + Modify the file $PGDATA/PG_VERSION from 5.0 to 5.1 - + + Start up a new 1.01 postmaster - + + Add the new built-in functions and operators of 1.01 to 1.0 @@ -1390,8 +1464,10 @@ create operator !~* (leftarg = char16, rightarg = text, procedure = char16icrege create operator ~* (leftarg = text, rightarg = text, procedure = texticregexeq); create operator !~* (leftarg = text, rightarg = text, procedure = texticregexne); - + + + Detailed Change List @@ -1431,6 +1507,9 @@ Bug fixes: * psql now returns non-zero status on errors when using -c * applied public patches 1-14 + + + Release v1.0 @@ -1493,6 +1572,9 @@ Bug fixes: * btrees with multiple index never worked, now we tell you they don't work when you try to use them + + + <productname>Postgres95</productname> Beta 0.03 @@ -1621,7 +1703,9 @@ New utilities: New documentation: * the user manual has been revised and libpq documentation added. - + + + <productname>Postgres95</productname> Beta 0.02 @@ -1678,7 +1762,9 @@ The following bugs have been fixed in postgres95-beta-0.02: * CREATE TYPE doesn't accept 'variable' as the internallength * wrong result using more than 1 aggregate in a SELECT - + + + <productname>Postgres95</productname> Beta 0.01 @@ -1698,7 +1784,8 @@ Mon May 1 19:03:10 PDT 1995 Initial release. - + + Timing Results @@ -1711,11 +1798,11 @@ These timing results are from running the regression test with the commands % make all % time make runtest - + Timing under Linux 2.0.27 seems to have a roughly 5% variation from run to run, presumably due to the scheduling vagaries of multitasking systems. - + v6.4beta @@ -1723,12 +1810,14 @@ These timing results are from running the regression test with the commands The times for this release are not directly comparable to those for previous releases since some additional regression tests have been included. In general, however, v6.4 should be slightly faster than the previous release (thanks, Bruce!). - + Time System 02:26 Dual Pentium Pro 180, 96MB, UW-SCSI, Linux 2.0.30, gcc 2.7.2.1 -O2 -m486 + + v6.3 @@ -1738,13 +1827,15 @@ The times for this release are not directly comparable to those for previous rel since some additional regression tests have been included and some obsolete tests involving time travel have been removed. In general, however, v6.3 is substantially faster than previous releases (thanks, Bruce!). - + Time System 02:30 Dual Pentium Pro 180, 96MB, UW-SCSI, Linux 2.0.30, gcc 2.7.2.1 -O2 -m486 04:12 Dual Pentium Pro 180, 96MB, EIDE, Linux 2.0.30, gcc 2.7.2.1 -O2 -m486 + + v6.1 @@ -1756,5 +1847,7 @@ In general, however, v6.3 is substantially faster than previous releases (thanks 12:06 P-100, 48MB, Linux 2.0.29, gcc 39:58 Sparc IPC 32MB, Solaris 2.5, gcc 2.7.2.1 -O -g - + + + diff --git a/doc/src/sgml/rules.sgml b/doc/src/sgml/rules.sgml index c3d7adb480..007b4dff1c 100644 --- a/doc/src/sgml/rules.sgml +++ b/doc/src/sgml/rules.sgml @@ -28,7 +28,7 @@ [] as well as []. - + What is a Querytree? @@ -224,6 +224,7 @@ + @@ -1020,7 +1021,7 @@ create zero or many new parsetrees and can throw away the original one. - + How These Rules Work @@ -1128,7 +1129,7 @@ - + Finally, if the rule is not INSTEAD, the unchanged original parsetree is added to the list. Since only qualified INSTEAD rules already add the diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index f699088119..774c19cae7 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -4,7 +4,7 @@ This chapter outlines the interaction between Postgres and the operating system. - + Using <Productname>Postgres</Productname> from Unix @@ -13,7 +13,7 @@ All Postgres commands that are executed directly from a Unix shell are found in the directory .../bin. Including this directory in your search path will make executing the commands easier. - + A collection of system catalogs exist at each site. These include a class (pg_user) that contains an instance for each valid @@ -26,6 +26,9 @@ user cannot do anything with Postgres until an appropriate instance is installed in this class. Further information on the system catalogs is available by running queries on the appropriate classes. + + + System Layout diff --git a/doc/src/sgml/signals.sgml b/doc/src/sgml/signals.sgml index c5e7a9372d..23625aed41 100644 --- a/doc/src/sgml/signals.sgml +++ b/doc/src/sgml/signals.sgml @@ -17,10 +17,12 @@ Contributed by Massimo Dal Zotto + Postgres uses the following signals for communication between the postmaster and backends: + @@ -32,103 +34,156 @@ Contributed by Massimo Dal Zotto Signal + postmaster Action + Server Action + + + SIGHUP + kill(*,sighup) + read_pg_options + + SIGINT + die + cancel query + + SIGQUIT + kill(*,sigterm) + handle_warn + + SIGTERM + kill(*,sigterm), kill(*,9), die + die + + SIGPIPE + ignored + die + + SIGUSR1 + kill(*,sigusr1), die + quickdie + + SIGUSR2 + kill(*,sigusr2) + async notify (SI flush) + + SIGCHLD + reaper + ignored (alive test) + + SIGTTIN + ignored + + + SIGTTOU + ignored + + + SIGCONT + dumpstatus + + + SIGFPE + + FloatExceptionHandler + + @@ -137,7 +192,9 @@ FloatExceptionHandler kill(*,signal) means sending a signal to all backends. + + The main changes to the old signal handling are the use of SIGQUIT instead @@ -148,6 +205,7 @@ In this way these signals sent to the postmaster can be sent automatically to all the backends without need to know their pids. To shut down postgres one needs only to send a SIGTERM to postmaster and it will stop automatically all the backends. + The SIGUSR2 signal is also used to prevent SI cache table overflow @@ -155,6 +213,7 @@ which happens when some backend doesn't process SI cache for a long period. When a backend detects the SI table full at 70% it simply sends a signal to the postmaster which will wake up all idle backends and make them flush the cache. + The typical use of signals by programmers could be the following: @@ -186,5 +245,5 @@ cat new_pg_options > $DATA_DIR/pg_options kill -HUP $backend_pid cat old_pg_options > $DATA_DIR/pg_options - + diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml index eb6b1d6679..ada3d321ed 100644 --- a/doc/src/sgml/spi.sgml +++ b/doc/src/sgml/spi.sgml @@ -127,6 +127,7 @@ Return status + @@ -263,7 +264,7 @@ SPI_finish(void) SPI_finish closes an existing connection to the Postgres backend. You should call this function after completing operations through the SPI manager. - + You may get the error return SPI_ERROR_UNCONNECTED if SPI_finish is called without having a current valid connection. @@ -408,7 +409,7 @@ Maximum number of tuples to return SPI_ERROR_OPUNKNOWN if type of query is unknown (this shouldn't occur). - + If execution of your query was successful then one of the following (non-negative) values will be returned: @@ -475,7 +476,7 @@ You may pass many queries in one string or query string may be executed. - + The actual number of tuples for which the (last) query was executed is returned in the global variable SPI_processed (if not SPI_OK_UTILITY). @@ -676,16 +677,16 @@ Pointer to an execution plan (parser+planner+optimizer) nargs is number of parameters ($1 ... $nargs - as in SQL-functions), and nargs may be 0 only if there is not any $1 in query. - + Execution of prepared execution plans is sometimes much faster so this feature may be useful if the same query will be executed many times. - + The plan returned by SPI_prepare may be used only in current invocation of the procedure since SPI_finish frees memory allocated for a plan. See SPI_saveplan. - + If successful, a non-null pointer will be returned. Otherwise, you'll get a NULL plan. In both cases SPI_result will be set like the value returned @@ -818,7 +819,7 @@ Execution plan location. NULL if unsuccessful. SPI_saveplan stores a plan prepared by SPI_prepare in safe memory protected from freeing by SPI_finish or the transaction manager. - + In the current version of Postgres there is no ability to store prepared plans in the system @@ -991,6 +992,7 @@ Number of tuples for which plan is to be executed was prepared with some parameters. + @@ -1010,6 +1012,8 @@ initialized as in initialized as in SPI_exec if successful + + @@ -1025,7 +1029,7 @@ initialized as in SPI_execp stores a plan prepared by SPI_prepare in safe memory protected from freeing by SPI_finish or the transaction manager. - + In the current version of Postgres there is no ability to store prepared plans in the system @@ -1169,6 +1173,7 @@ Copied tuple is NULL + @@ -1333,6 +1338,7 @@ New tuple with modifications is NULL + @@ -1352,6 +1358,7 @@ SPI_result attributes in tuple) + @@ -1474,6 +1481,7 @@ Valid one-based index number of attribute SPI_ERROR_NOATTRIBUTE if the named attribute is not found + @@ -1595,6 +1603,7 @@ SPI_result set to SPI_ERROR_NOATTRIBUTE on error + @@ -1731,6 +1740,7 @@ no output function available SPI_ERROR_NOOUTFUNC) + diff --git a/doc/src/sgml/start-ag.sgml b/doc/src/sgml/start-ag.sgml index caa2cb6eec..f0fdeb28c6 100644 --- a/doc/src/sgml/start-ag.sgml +++ b/doc/src/sgml/start-ag.sgml @@ -73,7 +73,7 @@ It is possible to create a database in a location other than the default location for the installation. Remember that all database access actually occurs through the database backend, so that any location specified must be accessible by the backend. - + Alternate database locations are created and referenced by an environment variable which gives the absolute path to the intended storage location. @@ -82,7 +82,7 @@ and must be writable by the postgres administrator account. Any valid environment variable name may be used to reference an alternate location, although using variable name with a prefix of PGDATA is recommended to avoid confusion and conflict with other variables. - + In previous versions of Postgres, @@ -123,7 +123,7 @@ Any environment variable can be used to reference alternate location, although it is preferred that the variables be prefixed with "PGDATA" to eliminate confusion and the possibility of conflicting with or overwriting other variables. - + To create a data storage area in PGDATA2, ensure that /home/postgres already exists and is writable @@ -137,13 +137,14 @@ Creating Postgres database system directory /home/postgres/data Creating Postgres database system directory /home/postgres/data/base - + To test the new location, create a database test by typing % createdb -D PGDATA2 test % destroydb test + @@ -158,7 +159,7 @@ and authorized you to use the database, you (as a user) may begin to start up /usr/local/pgsql/bin to your shell search path. In most cases, this is all you should have to do in terms of preparation. - + If you get the following error message from a Postgres diff --git a/doc/src/sgml/typeconv.sgml b/doc/src/sgml/typeconv.sgml index 451e85138e..f658ba8af7 100644 --- a/doc/src/sgml/typeconv.sgml +++ b/doc/src/sgml/typeconv.sgml @@ -6,6 +6,7 @@ mixing of different data types in the same expression. Postgres has extensive facilities for evaluating mixed-type expressions. + In many cases a user will not need @@ -14,16 +15,19 @@ However, the implicit conversions done by Postgres can affect the apparent results of a query, and these results can be tailored by a user or programmer using explicit type coersion. + This chapter introduces the Postgres type conversion mechanisms and conventions. Refer to the relevant sections in the User's Guide and Programmer's Guide for more information on specific data types and allowed functions and operators. + The Programmer's Guide has more details on the exact algorithms used for implicit type conversion and coersion. + Overview @@ -36,6 +40,7 @@ much more general and flexible than other RDBMS implementatio Hence, most type conversion behavior in Postgres should be governed by general rules rather than by ad-hoc heuristics to allow mixed-type expressions to be meaningful, even with user-defined types. + The Postgres scanner/parser decodes lexical elements @@ -56,11 +61,13 @@ Origin|(0,0) has two strings, of type text and point. If a type is not specified, then the placeholder type unknown is assigned initially, to be resolved in later stages as described below. + There are four fundamental SQL constructs requiring distinct type conversion rules in the Postgres parser: + @@ -72,6 +79,7 @@ Operators Postgres allows expressions with left- and right-unary (one argument) operators, as well as binary (two argument) operators. + @@ -83,6 +91,7 @@ Function calls Much of the Postgres type system is built around a rich set of functions. Function calls have one or more arguments which, for any specific query, must be matched to the functions available in the system catalog. + @@ -93,6 +102,7 @@ Query targets SQL INSERT statements place the results of query into a table. The expressions in the query must be matched up with, and perhaps converted to, the target columns of the insert. + @@ -103,6 +113,7 @@ UNION queries Since all select results from a UNION SELECT statement must appear in a single set of columns, the types of each SELECT clause must be matched up and converted to a uniform set. + @@ -113,6 +124,7 @@ the Postgres function and operator system tables. There are some heuristics included in the conversion rules to better support conventions for the SQL92 standard native types such as smallint, integer, and float. + The Postgres parser uses the convention that all @@ -122,6 +134,7 @@ criteria is considered to be a valid conversion function, and may be used by the parser as such. This simple assumption gives the parser the power to explore type conversion possibilities without hardcoding, allowing extended user-defined types to use these same features transparently. + An additional heuristic is provided in the parser to allow better guesses @@ -133,11 +146,13 @@ Each "user-defined" type is its own "preferred type", so ambiguous expressions (those with multiple candidate parsing solutions) with only one user-defined type can resolve to a single best choice, while those with multiple user-defined types will remain ambiguous and throw an error. + Ambiguous expressions which have candidate solutions within only one type category are likely to resolve, while ambiguous expressions with candidates spanning multiple categories are likely to throw an error and ask for clarification from the user. + Guidelines @@ -149,12 +164,16 @@ All type conversion rules are designed with several principles in mind: Implicit conversions should never have suprising or unpredictable outcomes. + + User-defined types, of which the parser has no apriori knowledge, should be "higher" in the type heirarchy. In mixed-type expressions, native types shall always be converted to a user-defined type (of course, only if conversion is necessary). + + @@ -162,6 +181,8 @@ User-defined types are not related. Currently, Postgres + @@ -170,12 +191,18 @@ if a query does not need implicit type conversion. That is, if a query is well formulated and the types already match up, then the query should proceed without spending extra time in the parser and without introducing unnecessary implicit conversion functions into the query. + Additionally, if a query usually requires an implicit conversion for a function, and if then the user defines an explicit function with the correct argument types, the parser should use this new function and will no longer do the implicit conversion using the old function. + + + + + Operators @@ -183,50 +210,55 @@ should use this new function and will no longer do the implicit conversion using Conversion Procedure - Operator Evaluation - Check for an exact match in the pg_operator system catalog. + If one argument of a binary operator is unknown, then assume it is the same type as the other argument. - + + Reverse the arguments, and look for an exact match with an operator which points to itself as being commutative. If found, then reverse the arguments in the parse tree and use this operator. - + + + Look for the best match. - + Make a list of all operators of the same name. - + + If only one operator is in the list, use it if the input type can be coerced, and throw an error if the type cannot be coerced. - + + Keep all operators with the most explicit matches for types. Keep all if there are no explicit matches and move to the next step. If only one candidate remains, use it if the type can be coerced. - + + If any input arguments are "unknown", categorize the input candidates as @@ -235,16 +267,20 @@ categories, or more than one user-defined type, throw an error because the correct choice cannot be deduced without more clues. If only one category is present, then assign the "preferred type" to the input column which had been previously "unknown". - + + Choose the candidate with the most exact type matches, and which matches the "preferred type" for each column category from the previous step. If there is still more than one candidate, or if there are none, then throw an error. + + - + + Examples @@ -291,7 +327,10 @@ Exp This last form has the least overhead, since no functions are called to do implicit type conversion. This is not an issue for small queries, but may have an impact on the performance of queries involving large tables. + + + String Concatenation @@ -300,6 +339,7 @@ have an impact on the performance of queries involving large tables. A string-like syntax is used for working with string types as well as for working with complex extended types. Strings with unspecified type are matched with likely operator candidates. + One unspecified argument: @@ -310,11 +350,13 @@ Text and Unknown abcdef (1 row) + In this case the parser looks to see if there is an operator taking text for both arguments. Since there is, it assumes that the second argument should be interpreted as of type text. + Concatenation on unspecified types: @@ -325,19 +367,23 @@ Unspecified abcdef (1 row) + In this case there is no initial hint for which type to use, since no types are specified in the query. So, the parser looks for all candidate operators and finds that all arguments for all the candidates are string types. It chooses the "preferred type" for strings, text, for this query. + If a user defines a new type and defines an operator || to work with it, then this query would no longer succeed as written. The parser would now have candidate types from two categories, and could not decide which to use. + + Factorial @@ -366,40 +412,43 @@ However, the role of a database is not to teach mathematics, but to be a tool for data manipulation. If a user chooses to take the factorial of a floating point number, Postgres will try to oblige. + + + + + Functions - - Function Evaluation Check for an exact match in the pg_proc system catalog. - + Look for the best match. - + Make a list of all functions of the same name with the same number of arguments. - + If only one function is in the list, use it if the input types can be coerced, and throw an error if the types cannot be coerced. - + Keep all functions with the most explicit matches for types. Keep all if there are no explicit matches and move to the next step. If only one candidate remains, use it if the type can be coerced. - + If any input arguments are "unknown", categorize the input candidate arguments as @@ -408,17 +457,17 @@ categories, or more than one user-defined type, throw an error because the correct choice cannot be deduced without more clues. If only one category is present, then assign the "preferred type" to the input column which had been previously "unknown". - + Choose the candidate with the most exact type matches, and which matches the "preferred type" for each column category from the previous step. If there is still more than one candidate, or if there are none, then throw an error. + - + - Examples @@ -446,6 +495,8 @@ int4fac 24 (1 row) + + Substring Function @@ -453,6 +504,7 @@ int4fac There are two substr functions declared in pg_proc. However, only one takes two arguments, of types text and int4. + If called with a string constant of unspecified type, the type is matched up @@ -464,6 +516,7 @@ substr 34 (1 row) + If the string is declared to be of type varchar, as might be the case @@ -483,12 +536,14 @@ substr 34 (1 row) + There are some heuristics in the parser to optimize the relationship between the char, varchar, and text types. For this case, substr is called directly with the varchar string rather than inserting an explicit conversion call. + @@ -509,22 +564,25 @@ substr 34 (1 row) + + + + Query Targets - - Target Evaluation Check for an exact match with the target. - + Try to coerce the expression directly to the target type if necessary. + @@ -532,6 +590,7 @@ If the target is a fixed-length type (e.g. char or varchar @@ -556,7 +615,10 @@ v abcd (1 row) - + + + + UNION Queries @@ -564,19 +626,20 @@ abcd The UNION construct is somewhat different in that it must match up possibly dissimilar types to become a single result set. - + UNION Evaluation Check for identical types for all results. + Coerce each result from the UNION clauses to match the type of the first SELECT clause or the target column. - + @@ -594,6 +657,8 @@ a b (2 rows) + + Simple UNION @@ -607,6 +672,8 @@ Float8 1.2 (2 rows) + + Transposed UNION @@ -626,7 +693,7 @@ All integers 3 (3 rows) - + An alternate parser strategy could be to choose the "best" type of the bunch, but this is more difficult because of the nice recursion technique used in the @@ -649,5 +716,8 @@ tgl=> SELECT f AS "Floating point" from ff; 3.3 (3 rows) - + + + + diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index cbad3a04ba..3bc1539372 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -72,6 +72,7 @@ +-------+ + <Acronym>SQL</Acronym> Functions on Composite Types @@ -98,7 +99,7 @@ |Sam | 2400 | +-----+-------+ - + Notice the use of the syntax $1.salary. Before launching into the subject of functions that @@ -122,7 +123,7 @@ |Sam | +----------+ - + As we shall see, however, this is not always the case. This function notation is important when we want to use @@ -156,6 +157,7 @@ The target list order must be exactly the same as that in which the attributes appear in the CREATE TABLE statement (or when you execute a .* query). + You must typecast the expressions @@ -165,6 +167,7 @@ You must typecast the expressions WARN::function declared to return type EMP does not retrieve (EMP.*) + When calling a function that returns an instance, we @@ -181,6 +184,7 @@ When calling a function that returns an instance, we +-------+ + The reason why, in general, we must use the function @@ -194,8 +198,9 @@ The reason why, in general, we must use the function WARN:parser: syntax error at or near "." + - + Any collection of commands in the SQL query language can be packaged together and defined as a function. @@ -219,6 +224,8 @@ The reason why, in general, we must use the function +--+ + + Programming Language Functions @@ -236,8 +243,11 @@ The reason why, in general, we must use the function Base types can have one of three internal formats: pass by value, fixed-length + pass by reference, fixed-length + pass by reference, variable-length + @@ -498,6 +508,7 @@ Most of the header (include) files for Postgres (where <PORTNAME> is the name of the port, e.g., alpha or sparc). + When allocating memory, use the Postgres @@ -507,6 +518,7 @@ Most of the header (include) files for Postgres automatically at the end of each transaction, preventing memory leaks. + Always zero the bytes of your structures using memset or bzero. Several routines (such as the @@ -517,12 +529,14 @@ Most of the header (include) files for Postgres several bytes of alignment padding (holes in the structure) that may contain garbage values. + Most of the internal Postgres types are declared in postgres.h, so it's a good idea to always include that file as well. Including postgres.h will also include elog.h and palloc.h for you. + Compiling and loading your object code so that it can be dynamically loaded into Postgres @@ -534,3 +548,6 @@ Most of the header (include) files for Postgres + + + diff --git a/doc/src/sgml/xindex.sgml b/doc/src/sgml/xindex.sgml index 820ebc9d29..6cec323864 100644 --- a/doc/src/sgml/xindex.sgml +++ b/doc/src/sgml/xindex.sgml @@ -196,7 +196,7 @@ Strictly speaking, this routine can return a negative number (< 0), 0, or a non-zero positive number (> 0). - + The amstrategies entry in pg_am is just the number of strategies defined for the access method in question. diff --git a/doc/src/sgml/xplang.sgml b/doc/src/sgml/xplang.sgml index feb1cc88a2..a87404bd61 100644 --- a/doc/src/sgml/xplang.sgml +++ b/doc/src/sgml/xplang.sgml @@ -28,15 +28,14 @@ Installing Procedural Languages - - + Procedural Language Installation A procedural language is installed in the database in three steps. - + The shared object for the language handler @@ -82,9 +81,9 @@ PL/Tcl are known to be trusted. - - - + + + Example @@ -132,7 +131,7 @@ languages are available by default. - +