From 654f8f0b51c0860e17f025dbe8770bf0f8722697 Mon Sep 17 00:00:00 2001 From: "Thomas G. Lockhart" Date: Sat, 22 May 1999 02:27:25 +0000 Subject: [PATCH] Finish initial markup of cvs.sgml, and include it in the programmer's guide and the integrated doc. Clean up other markup. --- doc/src/sgml/cvs.sgml | 1439 +++++++++++++--------------------- doc/src/sgml/datetime.sgml | 814 ++++++++++++++++--- doc/src/sgml/pg_options.sgml | 2 +- doc/src/sgml/postgres.sgml | 12 +- doc/src/sgml/programmer.sgml | 8 +- doc/src/sgml/query.sgml | 3 - doc/src/sgml/sql.sgml | 6 +- doc/src/sgml/user.sgml | 10 +- doc/src/sgml/xoper.sgml | 86 +- 9 files changed, 1323 insertions(+), 1057 deletions(-) diff --git a/doc/src/sgml/cvs.sgml b/doc/src/sgml/cvs.sgml index 74be5e13bd..aadf0027fa 100644 --- a/doc/src/sgml/cvs.sgml +++ b/doc/src/sgml/cvs.sgml @@ -1,9 +1,13 @@ - - - - -Marc -Fournier - - -1998-12-01 - + + + + + Marc + Fournier + + + Tom + Lane + + + Thomas + Lockhart + + + 1999-05-20 + - The <productname>Postgres</productname> <productname>CVS</productname> Repository + The <productname>CVS</productname> Repository The Postgres source code is stored and managed using the CVS code management system. - At least two options, - anonymous CVS and CVSup, - are available to pull the CVS code tree from the - Postgres server to your local machine. - + + At least two options, + anonymous CVS and CVSup, + are available to pull the CVS code tree from the + Postgres server to your local machine. + <productname>CVS</productname> Tree Organization @@ -53,37 +66,39 @@ Not yet included in a document (should go in the developer's doc?). Author Written by Marc G. Fournier on 1998-11-05. + - + The command cvs checkout has a flag, , - that lets you check out a -certain revision of a module. This flag makes it easy to, for example, -retrieve the -sources that make up release 1.0 of the module `tc' at any time in the -future: + that lets you check out a + certain revision of a module. This flag makes it easy to, for example, + retrieve the + sources that make up release 1.0 of the module `tc' at any time in the + future: - + $ cvs checkout -r REL6_4 tc - + -This is useful, for instance, if someone claims that there is a bug in -that release, but you cannot find the bug in the current working copy. + This is useful, for instance, if someone claims that there is a bug in + that release, but you cannot find the bug in the current working copy. - - - You can also check out a module as it was at any given date using the - option. - - + + + You can also check out a module as it was at any given date using the + option. + + + - + When you tag more than one file with the same tag you can think -about the tag as "a curve drawn through a matrix of filename vs. -revision number". Say we have 5 files with the following revisions: - - + about the tag as "a curve drawn through a matrix of filename vs. + revision number". Say we have 5 files with the following revisions: + + file1 file2 file3 file4 file5 1.1 1.1 1.1 1.1 /--1.1* <-*- TAG @@ -92,466 +107,598 @@ revision number". Say we have 5 files with the following revisions: 1.4 \ 1.4 / 1.4 \-1.5*- 1.5 1.6 - + -then the tag TAG will reference -file1-1.2, file2-1.3, etc. + then the tag TAG will reference + file1-1.2, file2-1.3, etc. - - -For creating a release branch, other then a --b option added to the command, it's the same thing. - - + + + For creating a release branch, other then a + -b option added to the command, it's the same thing. + + - -So, to create the v6.4 release -I will be doing the following: + + So, to create the v6.4 release + I did the following: - + $ cd pgsql $ cvs tag -b REL6_4 - + -which will create the tag and the branch for the RELEASE tree. - + which will create the tag and the branch for the RELEASE tree. + - -Now, for those with CVS access, it's too simple. -First, create two subdirectories, RELEASE and CURRENT, so that you don't -mix up the two. Then do: + + Now, for those with CVS access, it's too simple. + First, create two subdirectories, RELEASE and CURRENT, so that you don't + mix up the two. Then do: - + cd RELEASE cvs checkout -P -r REL6_4 pgsql cd ../CURRENT cvs checkout -P pgsql - + -which results in two directory trees, RELEASE/pgsql and -CURRENT/pgsql. From that point on, CVS -will keep track of which repository branch is in which directory tree, and will -allow independent updates of either tree. - + which results in two directory trees, RELEASE/pgsql and + CURRENT/pgsql. From that point on, + CVS + will keep track of which repository branch is in which directory tree, and will + allow independent updates of either tree. + - -If you are only working on the CURRENT - source tree, you just do -everything as before we started tagging release branches. - + + If you are only working on the CURRENT + source tree, you just do + everything as before we started tagging release branches. + - -After you've done the initial checkout on a branch + + After you've done the initial checkout on a branch - + $ cvs checkout -r REL6_4 - + -anything you do within that directory structure is restricted to that -branch. If you apply a patch to that directory structure and do a + anything you do within that directory structure is restricted to that + branch. If you apply a patch to that directory structure and do a - + cvs commit - - while inside of it, the patch is applied to the branch and -only the branch. - - + - -Getting The Source Via Anonymous <productname>CVS</productname> + while inside of it, the patch is applied to the branch and + only the branch. + + - -If you would like to keep up with the current sources on a regular -basis, you can fetch them from our CVS server -and then use CVS to -retrieve updates from time to time. - + + Getting The Source Via Anonymous <productname>CVS</productname> - -Anonymous CVS + + If you would like to keep up with the current sources on a regular + basis, you can fetch them from our CVS server + and then use CVS to + retrieve updates from time to time. + - - -You will need a local copy of CVS (Concurrent Version Control -System), which you can get from -http://www.cyclic.com/ or -any GNU software archive site. -We currently recommend version 1.10 (the most recent at the time of writing). - - + + Anonymous CVS - - -Do an initial login to the CVS server: - -cvs -d :pserver:anoncvs@postgresql.org:/usr/local/cvsroot login - -You will be prompted for a password; enter 'postgresql'. -You should only need to do this once, since the password will be -saved in .cvspass in your home directory. - - + + + You will need a local copy of CVS + (Concurrent Version Control System), which you can get from + http://www.cyclic.com/ or + any GNU software archive site. + We currently recommend version 1.10 (the most recent at the time + of writing). Many systems have a recent version of + cvs installed by default. + + - - -Fetch the Postgres sources: - + + + Do an initial login to the CVS server: + + +$ cvs -d :pserver:anoncvs@postgresql.org:/usr/local/cvsroot login + + + You will be prompted for a password; enter 'postgresql'. + You should only need to do this once, since the password will be + saved in .cvspass in your home directory. + + + + + + Fetch the Postgres sources: + cvs -z3 -d :pserver:anoncvs@postgresql.org:/usr/local/cvsroot co -P pgsql - -which installs the Postgres sources into a -subdirectory pgsql -of the directory you are currently in. + - - -If you have a fast link to the Internet, you may not need , -which instructs CVS to use gzip compression for transferred data. But -on a modem-speed link, it's a very substantial win. - - + which installs the Postgres sources into a + subdirectory pgsql + of the directory you are currently in. - -This initial checkout is a little slower than simply downloading -a tar.gz file; expect it to take 40 minutes or so if you -have a 28.8K modem. The advantage of CVS doesn't show up until you -want to update the file set later on. - - + + + If you have a fast link to the Internet, you may not need + , which instructs + CVS to use gzip compression for transferred data. But + on a modem-speed link, it's a very substantial win. + + + - - -Whenever you want to update to the latest CVS sources, -cd into -the pgsql subdirectory, and issue - -cvs -z3 update -d -P - -This will fetch only the changes since the last time you updated. -You can update in just a couple of minutes, typically, even over -a modem-speed line. - - + + This initial checkout is a little slower than simply downloading + a tar.gz file; expect it to take 40 minutes or so if you + have a 28.8K modem. The advantage of + CVS + doesn't show up until you want to update the file set later on. + + - - -You can save yourself some typing by making a file .cvsrc -in your home directory that contains + + + Whenever you want to update to the latest CVS sources, + cd into + the pgsql subdirectory, and issue + +$ cvs -z3 update -d -P + - + This will fetch only the changes since the last time you updated. + You can update in just a couple of minutes, typically, even over + a modem-speed line. + + + + + + You can save yourself some typing by making a file .cvsrc + in your home directory that contains + + cvs -z3 update -d -P - + -This supplies the option to all cvs commands, and the - and options to cvs update. Then you just have -to say - -cvs update - -to update your files. - - - + This supplies the option to all cvs commands, and the + and options to cvs update. Then you just have + to say + +$ cvs update + - - -Some older versions of CVS have a bug that -causes all checked-out files to be stored world-writable in your -directory. If you see that this has happened, you can do something like - -chmod -R go-w pgsql - -to set the permissions properly. -This bug is fixed as of CVS version 1.9.28. - - + to update your files. + + + - -CVS can do a lot of other things, such as fetching prior revisions -of the Postgres sources rather than the latest development version. -For more info consult the manual that comes with CVS, or see the online -documentation at http://www.cyclic.com/. - + + + Some older versions of CVS have a bug that + causes all checked-out files to be stored world-writable in your + directory. If you see that this has happened, you can do something like + +$ chmod -R go-w pgsql + + to set the permissions properly. + This bug is fixed as of + CVS version 1.9.28. + + - + + CVS can do a lot of other things, + such as fetching prior revisions + of the Postgres sources + rather than the latest development version. + For more info consult the manual that comes with + CVS, or see the online + documentation at + http://www.cyclic.com/. + + - -Getting The Source Via <productname>CVSup</productname> + + Getting The Source Via <productname>CVSup</productname> - -An alternative to using anonymous CVS for retrieving -the Postgres source tree -is CVSup. The major advantage to using -CVSup is that it can reliably -replicate the entire CVS repository on your local system, -allowing fast local access to cvs operations such as -and . Other advantages include fast synchronization to -the Postgres server due to an efficient -streaming transfer protocol which only sends the changes since the last update. - + + An alternative to using anonymous CVS for retrieving + the Postgres source tree + is CVSup. + CVSup was developed by + John Polstra to + distribute CVS repositories and other file trees for + the FreeBSD project. + - -Installation from Binaries + + A major advantage to using + CVSup is that it can reliably + replicate the entire CVS repository on your local system, + allowing fast local access to cvs operations such as + and . Other advantages include fast synchronization to + the Postgres server due to an efficient + streaming transfer protocol which only sends the changes since the last update. + - -Instructions for installing CVSup from sources -are in a subsequent section. You can instead use pre-built binaries -if you have a platform for which binaries -are posted on -the Postgres ftp site, -or if you are running FreeBSD, for which CVSup is available -as a port. - + + Preparing A <productname>CVSup</productname> Client System - - -Retrieve the binary tar file appropriate for your platform. + + Two directory areas are required for CVSup + to do it's job: a local CVS repository + (or simply a directory area if you are fetching a snapshot rather + than a repository; see below) + and a local CVSup bookkeeping + area. These can coexist in the same directory tree. + - - - -If you are running FreeBSD, install the CVSup port. - - + + Decide where you want to keep your local copy of the + CVS repository. On one of our systems we + recently set up a repository in /home/cvs/, + but had formerly kept it under a + Postgres development tree in + /opt/postgres/cvs/. If you intend to keep your + repository in /home/cvs/, then put - - -If you have another platform, check for and download the appropriate binary from -the Postgres ftp site, - - - - + +setenv CVSROOT /home/cvs + - - - + in your .cshrc file, or a similar line in + your .bashrc or + .profile file, depending on your shell. + - + + The cvs repository area must be initialized. + Once CVSROOT is set, then this can be done with a + single command: - -Installation from Binaries + +$ cvs init + - -Instructions for installing CVSup from sources -are in a subsequent section. If you have a platform for which static binaries -are posted on -the Postgres ftp site. - + after which you should see at least a directory named + CVSROOT when listing the + CVSROOT directory: - -Client Configuration + +$ ls $CVSROOT +CVSROOT/ + + + - - + + Running a <productname>CVSup</productname> Client - -Background + + Verify that + cvsup is in your path; on most systems + you can do this by typing - - -Author - -Written by John Polstra, the -CVSup author. - + +which cvsup + -Before you dismiss CVSup because of the language it's written in, -I hope you'll take a look at the long list of platforms supported -by the free DEC SRC Modula-3 compiler, at: + Then, simply run + cvsup using: - http://www.research.digital.com/SRC/modula-3/html/platforms.html + +$ cvsup -L 2 postgres.cvsup + -I developed CVSup using that compiler, under FreeBSD. I also have -reports from people who are using CVSup under Linux, Solaris, and -ALPHA/OSF. It should be easily portable to any of the POSIX systems -supported by the compiler. + where enables some status messages so you + can monitor the progress of the update, + and postgres.cvsup is + the path and name you have given to your + CVSup configuration file. + -I understand your reluctance to "change a winning team," but once -you've seen the speed increase of CVSup relative to sup, you'll no -longer view sup as "winning." Sup was the inspiration for me to -develop CVSup, precisely because it performs so badly in certain -situations. + + Here is a CVSup configuration file + modified for a specific installation, and which maintains a full + local CVS repository: -Sup's synchronous request-ack communication pattern is death on a -high-latency network link. CVSup uses a streaming protocol that is -immune to latency problems. Its multi-threaded implementation -utilizes the network link in both directions simultaneously, at or -near its capacity. + +# This file represents the standard CVSup distribution file +# for the PostgreSQL ORDBMS project +# Modified by lockhart@alumni.caltech.edu 1997-08-28 +# - Point to my local snapshot source tree +# - Pull the full CVS repository, not just the latest snapshot +# +# Defaults that apply to all the collections +*default host=postgresql.org +*default compress +*default release=cvs +*default delete use-rel-suffix +# enable the following line to get the latest snapshot +#*default tag=. +# enable the following line to get whatever was specified above or by default +# at the date specified below +#*default date=97.08.29.00.00.00 -If you are mirroring a CVS repository and add a tag to each file -(say, to make an official release), sup will send a fresh copy of -every file in the repository. CVSup sends only the tags, and edits -them into the files on the client host. It was just such a tagging -operation, and the attendent utter saturation of their server's -network link, that led the FreeBSD project to abandon sup in favor -of CVSup. If you ask on , I'm sure -you'll get some opinions on whether CVSup is worth its Modula-3 -hassle factor. +# base directory points to where CVSup will store its 'bookmarks' file(s) +# will create subdirectory sup/ +#*default base=/opt/postgres # /usr/local/pgsql +*default base=/home/cvs -It's freeware. I don't get anything besides warm fuzzy feelings -when people use it. But I'd hate to see you rule it out simply -because of the language it's written in. +# prefix directory points to where CVSup will store the actual distribution(s) +*default prefix=/home/cvs -If I can answer any questions about CVSup or Modula-3, feel free -to contact me. +# complete distribution, including all below +pgsql -Best regards, -John Polstra --- - John Polstra jdp@polstra.com - John D. Polstra & Co., Inc. Seattle, Washington USA - "Self-knowledge is always bad news." -- John Barth +# individual distributions vs 'the whole thing' +# pgsql-doc +# pgsql-perl5 +# pgsql-src + + + + The following is a suggested CVSup config file from + the Postgres ftp site + which will fetch the current snapshot only: - -Installing <productname>CVSup</productname> + +# This file represents the standard CVSup distribution file +# for the PostgreSQL ORDBMS project +# +# Defaults that apply to all the collections +*default host=postgresql.org +*default compress +*default release=cvs +*default delete use-rel-suffix +*default tag=. - -Binary files of CVSup client executables compiled -for several platforms are posted on -the PostgreSQL ftp site. -In many cases, these binary files will be sufficient to get started with -CVSup. - +# base directory points to where CVSup will store its 'bookmarks' file(s) +*default base=/usr/local/pgsql - -Alternatively, you can install CVSup from -a FreeBSD package or from source. A clean installation from source code -requires installation of a Modula-3 compiler, -which is also available as Linux RPM, - FreeBSD package, or source code. +# prefix directory points to where CVSup will store the actual distribution(s) +*default prefix=/usr/local/pgsql - - -A clean-source installation of Modula-3 takes roughly 200MB of disk space, -which shrinks to roughly 50MB of space when the sources are removed. - - +# complete distribution, including all below +pgsql - -Linux installation +# individual distributions vs 'the whole thing' +# pgsql-doc +# pgsql-perl5 +# pgsql-src - -For a CVSup client, pick up the appropriate tarball -from the PostgreSQL ftp site. -Unpack the tarball into /usr/local/bin, then move the man page -file cvsup.1 to /usr/local/man/man1. - + + + - -To build CVSup from local sources, - pick up the Modula-3 -distribution from -Polytechnique Montréal, - who are actively maintaining the code base originally developed by -the DEC Systems Research Center. -The PM3 RPM distribution is roughly -30MB compressed. - + + Installing <productname>CVSup</productname> -From - Tue Dec 1 14:01:42 1998 -Return-Path: -Received: from eis-msg-012.jpl.nasa.gov ([137.78.68.42]) - by eis-msg-002.jpl.nasa.gov (Netscape Mail Server v2.02) - with ESMTP id ADD868 for ; - Mon, 21 Jul 1997 11:44:48 -0700 -Return-Path: -Received: from mythos.jpl.nasa.gov by eis-msg-012.jpl.nasa.gov; Mon, 21 Jul 1997 11:44:50 -0700 -Received: by mythos.jpl.nasa.gov (5.65v3.2/1.1.10.5/11Jan97-0348AM) - id AA24680; Mon, 21 Jul 1997 18:45:05 GMT -Received: from pyros.jpl.nasa.gov by mythos.jpl.nasa.gov (5.65v3.2/1.1.10.5/11Jan97-0348AM) - id AA26520; Mon, 21 Jul 1997 18:44:59 GMT -Received: from eis-msg-012.jpl.nasa.gov by pyros.jpl.nasa.gov (5.65v3.2/1.1.8.2/15Aug95-1038PM) - id AA26023; Mon, 21 Jul 1997 18:44:59 GMT -Received: from austin.polstra.com by eis-msg-012.jpl.nasa.gov with ESMTP; Mon, 21 Jul 1997 11:44:40 -0700 -Received: from austin.polstra.com (jdp@localhost) - by austin.polstra.com (8.8.6/8.8.5) with ESMTP id LAA00444 - for ; Mon, 21 Jul 1997 11:44:47 -0700 (PDT) -Message-Id: <199707211844.LAA00444@austin.polstra.com> -To: "Thomas G. Lockhart" -Subject: Re: [HACKERS] Re: CVSup is in Modula-3 -In-Reply-To: Your message of "Mon, 21 Jul 1997 16:31:17 -0000." - <33D38ED5.132C8923@jpl.nasa.gov> -References: <199705210339.UAA13067@austin.polstra.com> - <33D38ED5.132C8923@jpl.nasa.gov> -Date: Mon, 21 Jul 1997 11:44:47 -0700 -From: John Polstra -X-Mozilla-Status: 0011 -Content-Length: 1113 + + CVSup is available as source, pre-built + binaries, or Linux RPMs. It is far easier to use a binary than to + build from source, primarily because the very capable, but + voluminous, Modula-3 compiler is required for the build. + -Tom, + + <productname>CVSup</productname> Installation from Binaries -> We are starting to try to set up CVSup to support the PostgreSQL -> project. + + You can instead use pre-built binaries + if you have a platform for which binaries + are posted on + the Postgres ftp site, + or if you are running FreeBSD, for which + CVSup is available as a port. -Great! If I can help, just let me know. + + + CVSup was originally developed as a + tool for distributing the FreeBSD + source tree. It is available as a "port", and for those running + FreeBSD, if this is not sufficient to tell how to obtain and + install it then please contribute a procedure here. + + + -> After being delayed while buying more disk to install Modula-3, + + At the time of writing, binaries are available for + Alpha/Tru64, ix86/xBSD, + HPPA/HPUX-10.20, and MIPS/irix. + ix86/linux-libc5, ix86/linux-glibc, + Sparc/Solaris, and Sparc/SunOS. + -:-} + + + Retrieve the binary tar file for + cvsup + (cvsupd is not required + to be a client) appropriate for your platform. + -> I started back up on trying the installation. I have gotten the -> CVSup source distribution cvsup-15.1.tar.gz from www.cdrom.com and -> have m3 on my system, which already had zlib. -> -> There appears to be more needed on my RedHat Linux box; make fails -> with a syntax error on the last line of the Makefile which is -> -> .include -> -> I assume this is a FreeBSDism + + + + If you are running FreeBSD, install the CVSup port. + + + + + + If you have another platform, check for and download the appropriate binary from + the Postgres ftp site, + + + + -Yes, sorry, the Makefiles aren't portable yet. It's easy to build -it by hand though. Chdir into each of the following directories in -the given order, and in each one type "m3build": + + + Check the tar file to verify the contents and directory + structure, if any. For the linux tar file at least, the static binary + and man page is included without any directory packaging. + - suptcp - suplib - server - client + + + + If the binary is in the top level of the tar file, then simply + unpack the tar file into your target directory: -If all goes well, the executables will get created in the -subdirectories "server/LINUXELF" and "client/LINUXELF". + +$ cd /usr/local/bin +$ tar zxvf /usr/local/src/cvsup-16.0-linux-i386.tar.gz +$ mv cvsup.1 ../doc/man/man1/ + + + -If you run into any portability problems, please let me know and -I'll try to send you patches right away. It's the only way I know -of to improve the portability of the package. + + + If there is a directory structure in the tar file, then unpack + the tar file within /usr/local/src and move the binaries into + the appropriate location as above. + + + + -John + + + Ensure that the new binaries are in your path. -From - Tue Dec 1 14:02:37 1998 -Return-Path: -Received: from eis-msg-012.jpl.nasa.gov ([137.78.68.42]) - by eis-msg-002.jpl.nasa.gov (Netscape Mail Server v2.02) - with ESMTP id ADT23584 for ; - Mon, 21 Jul 1997 22:23:30 -0700 -Return-Path: -Received: from mythos.jpl.nasa.gov by eis-msg-012.jpl.nasa.gov; Mon, 21 Jul 1997 22:23:30 -0700 -Received: by mythos.jpl.nasa.gov (5.65v3.2/1.1.10.5/11Jan97-0348AM) - id AA27710; Tue, 22 Jul 1997 05:23:46 GMT -Received: from pyros.jpl.nasa.gov by mythos.jpl.nasa.gov (5.65v3.2/1.1.10.5/11Jan97-0348AM) - id AA27627; Tue, 22 Jul 1997 05:23:45 GMT -Received: from eis-msg-012.jpl.nasa.gov by pyros.jpl.nasa.gov (5.65v3.2/1.1.8.2/15Aug95-1038PM) - id AA16826; Tue, 22 Jul 1997 05:23:44 GMT -Received: from austin.polstra.com by eis-msg-012.jpl.nasa.gov with ESMTP; Mon, 21 Jul 1997 22:22:24 -0700 -Received: from austin.polstra.com (jdp@localhost) - by austin.polstra.com (8.8.6/8.8.5) with ESMTP id WAA04594 - for ; Mon, 21 Jul 1997 22:22:40 -0700 (PDT) -Message-Id: <199707220522.WAA04594@austin.polstra.com> -To: "Thomas G. Lockhart" -Subject: Re: [HACKERS] Re: CVSup is in Modula-3 -In-Reply-To: Your message of "Tue, 22 Jul 1997 04:55:24 -0000." - <33D43D3C.65F75F5@jpl.nasa.gov> -References: <199705210339.UAA13067@austin.polstra.com> <33D38ED5.132C8923@jpl.nasa.gov> <199707211844.LAA00444@austin.polstra.com> <33D409F9.5FEF02C7@jpl.nasa.gov> <199707220156.SAA03432@austin.polstra.com> - <33D43D3C.65F75F5@jpl.nasa.gov> -Date: Mon, 21 Jul 1997 22:22:40 -0700 -From: John Polstra -X-Mozilla-Status: 0011 -Content-Length: 2890 + +$ rehash +$ which cvsup +$ set path=(path to cvsup $path) +$ which cvsup +/usr/local/bin/cvsup + + + + + + + Installation from Sources + + + Installing CVSup from sources is not + entirely trivial, primarily because most systems will need to + install a Modula-3 compiler first. + This compiler is available as Linux RPM, + FreeBSD package, or source code. + + + + A clean-source installation of Modula-3 takes roughly 200MB of disk space, + which shrinks to roughly 50MB of space when the sources are removed. + + + + + Linux installation + + + + Install Modula-3. + + + + + + Pick up the Modula-3 + distribution from + Polytechnique Montréal, + who are actively maintaining the code base originally developed by + the DEC Systems Research Center. + The PM3 RPM distribution is roughly + 30MB compressed. At the time of writing, the 1.1.10-1 release + installed cleanly on RH-5.2, whereas the 1.1.11-1 release is + apparently built for another release (RH-6.0?) and does not run on RH-5.2. + + + + This particular rpm packaging has + many RPM files, + so you will likely want to place them into a separate + directory. + + + + + + + + Install the Modula-3 rpms: + + +# rpm -Uvh pm3*.rpm + + + + + + + + + Unpack the cvsup distribution: + + +# cd /usr/local/src +# tar zxf cvsup-16.0.tar.gz + + + + + + + Build the cvsup distribution, suppressing the GUI interface + feature to avoid requiring X11 libraries: + + +# make M3FLAGS="-DNOGUI" + + + and if you want to build a static binary to move to systems + which may not have Modula-3 installed, try: + + +# make M3FLAGS="-DNOGUI -DSTATIC" + + + + + + + Install the built binary: + + +# make M3FLAGS="-DNOGUI -DSTATIC" install + + + + + + + + + -> > I have a question about dates. -> > The Gregorian reform of calendar skiped 10 days on Oct, 1582. -> > This reform was accepted by Great Britain and Dominions (including -> > what is now the USA) only in 1752. -> > If I insert a date that doesn't exist PostgreSQL accepts it. -> > Should it be considered normal ? -> -> As Peter says, this is tricky. -> -> Date conventions before the 19th century make for interesting reading, -> but are not imho consistant enough to warrant coding into a date/time -> handler. -> -> As you probably have noticed, we use Julian date calculations for our -> date/time support. + + Date/Time Support -I suppose you refer to Julian Day invented by the French scholar -Joseph Justus Scaliger (1540-1609) -that probably takes its name from the Scaliger's father, -the Italian scholar Julius Caesar Scaliger (1484-1558). -Astronomers have used the Julian period to assign a unique number to -every day since 1 January 4713 BC. This is the so-called Julian Day -(JD). JD 0 designates the 24 hours from noon UTC on 1 January 4713 BC -to noon UTC on 2 January 4713 BC. + + Time Zones -Julian Day is different from Julian Date + + + <productname>Postgres</productname> Recognized Time Zones + Time Zones + + + + Time Zone + Offset from UTC + Description + + + + + NZDT + +13:00 + New Zealand Daylight Time + + + IDLE + +12:00 + International Date Line, East + + + NZST + +12:00 + New Zealand Std Time + + + NZT + +12:00 + New Zealand Time + + + AESST + +11:00 + Australia Eastern Summer Std Time + + + ACSST + +10:30 + Central Australia Summer Std Time + + + CADT + +10:30 + Central Australia Daylight Savings Time + + + SADT + +10:30 + South Australian Daylight Time + + + AEST + +10:00 + Australia Eastern Std Time + + + EAST + +10:00 + East Australian Std Time + + + GST + +10:00 + Guam Std Time, USSR Zone 9 + + + LIGT + +10:00 + Melbourne, Australia + + + ACST + +09:30 + Central Australia Std Time + + + CAST + +09:30 + Central Australia Std Time + + + SAT + +9:30 + South Australian Std Time + + + AWSST + +9:00 + Australia Western Summer Std Time + + + JST + +9:00 + Japan Std Time,USSR Zone 8 + + + KST + +9:00 + Korea Standard Time + + + WDT + +9:00 + West Australian Daylight Time + + + MT + +8:30 + Moluccas Time + + + AWST + +8:00 + Australia Western Std Time + + + CCT + +8:00 + China Coastal Time + + + WADT + +8:00 + West Australian Daylight Time + + + WST + +8:00 + West Australian Std Time + + + JT + +7:30 + Java Time + + + WAST + +7:00 + West Australian Std Time + + + IT + +3:30 + Iran Time + + + BT + +3:00 + Baghdad Time + + + EETDST + +3:00 + Eastern Europe Daylight Savings Time + + + CETDST + +2:00 + Central European Daylight Savings Time + + + EET + +2:00 + Eastern Europe, USSR Zone 1 + + + FWT + +2:00 + French Winter Time + + + IST + +2:00 + Israel Std Time + + + MEST + +2:00 + Middle Europe Summer Time + + + METDST + +2:00 + Middle Europe Daylight Time + + + SST + +2:00 + Swedish Summer Time + + + BST + +1:00 + British Summer Time + + + CET + +1:00 + Central European Time + + + DNT + +1:00 + Dansk Normal Tid + + + DST + +1:00 + Dansk Standard Time (?) + + + FST + +1:00 + French Summer Time + + + MET + +1:00 + Middle Europe Time + + + MEWT + +1:00 + Middle Europe Winter Time + + + MEZ + +1:00 + Middle Europe Zone + + + NOR + +1:00 + Norway Standard Time + + + SET + +1:00 + Seychelles Time + + + SWT + +1:00 + Swedish Winter Time + + + WETDST + +1:00 + Western Europe Daylight Savings Time + + + GMT + 0:00 + Greenwish Mean Time + + + WET + 0:00 + Western Europe + + + WAT + -1:00 + West Africa Time + + + NDT + -2:30 + Newfoundland Daylight Time + + + ADT + -03:00 + Atlantic Daylight Time + + + NFT + -3:30 + Newfoundland Standard Time + + + NST + -3:30 + Newfoundland Standard Time + + + AST + -4:00 + Atlantic Std Time (Canada) + + + EDT + -4:00 + Eastern Daylight Time + + + ZP4 + -4:00 + GMT +4 hours + + + CDT + -5:00 + Central Daylight Time + + + EST + -5:00 + Eastern Standard Time + + + ZP5 + -5:00 + GMT +5 hours + + + CST + -6:00 + Central Std Time + + + MDT + -6:00 + Mountain Daylight Time + + + ZP6 + -6:00 + GMT +6 hours + + + MST + -7:00 + Mountain Standard Time + + + PDT + -7:00 + Pacific Daylight Time + + + PST + -8:00 + Pacific Std Time + + + YDT + -8:00 + Yukon Daylight Time + + + HDT + -9:00 + Hawaii/Alaska Daylight Time + + + YST + -9:00 + Yukon Standard Time + + + AHST + -10:00 + Alaska-Hawaii Std Time + + + CAT + -10:00 + Central Alaska Time + + + NT + -11:00 + Nome Time + + + IDLW + -12:00 + International Date Line, West + + + +
+ + + If the compiler option USE_AUSTRALIAN_RULES is set + then EST refers to Australia Eastern Std Time, + which has an offset of +10:00 hours from UTC. + + + -The Julian calendar was introduced by Julius Caesar in 45 BC. It was -in common use until the 1582, when countries started changing to the -Gregorian calendar. + + Australian time zones and their naming variants + account for fully one quarter of all time zones in the + Postgres time zone lookup table. + -In the Julian calendar, the tropical year is approximated as 365 1/4 -days = 365.25 days. This gives an error of 1 day in approximately 128 + + Date/Time Input Interpretation -and this is why pope Gregory XIII in accordance with instructions -from the Council of Trent reformed the calendar to correct this error. + + The date/time types are all decoded using a common set of routines. + -In the Gregorian calendar, the tropical year is approximated as -365 + 97 / 400 days = 365.2425 days. Thus it takes approximately 3300 -years for the tropical year to shift one day with respect to the -Gregorian calendar. + + + Break the input string into tokens and categorize each token as + a string, time, time zone, or number. + -The approximation 365+97/400 is achieved by having 97 leap years -every 400 years. + + + + If the token contains a colon (":"), this is a time string. + + -The Gregorian calendar has 97 leap years every 400 years: + + + If the token contains a dash ("-"), slash ("/"), or dot ("."), + this is a date string which may have a text month. + + + + + If the token is numeric only, then it is either a single field + or an ISO-8601 concatenated date (e.g. "19990113" for January 13, 1999) + or time (e.g. 141516 for 14:15:16). + + + + + If the token starts with a plus ("+") or minus ("-"), + then it is either a time zone or a special field. + + + + + + + + If the token is a text string, match up with possible strings. + + + + + + Do a binary-search table lookup for the token + as either a special string (e.g. today), + day (e.g. Thursday), + month (e.g. January), or noise word (e.g. on). + + + Set field values and bit mask for fields. + For example, set year, month, day for today, and additionally + hour, minute, second for now. + + + + + + If not found, do a similar binary-search table lookup to match + the token with a time zone. + + + + + + If not found, throw an error. + + + + + + + + The token is a number or number field. + If there are more than 4 digits, + and if no other date fields have been previously read, then interpret + as a "concatenated date" (e.g. 19990118). + + + + + + If there are more than 4 digits, + and if no other date fields have been previously read, then interpret + as a "concatenated date" (e.g. 19990118). + + + + + + If three digits and a year has already been decoded, then interpret as day of year. + + + + + + If longer than two digits, then interpret as a year. + + + + + + If in European date mode, and if the day field has not yet been read, + and if the value is less than or equal to 31, then interpret as a day. + + + + + + If in non-European (US) date mode, and if the month field has not yet been read, + and if the value is less than or equal to 12, then interpret as a month. + + + + + + If the day field has not yet been read, + and if the value is less than or equal to 31, then interpret as a month. + + + + + + If the month field has not yet been read, + and if the value is less than or equal to 12, then interpret as a month. + + + + + + Otherwise, interpret as a year. + + + + + + + + If BC has been specified, negate the year and offset by one + (there is no year zero in the Gregorian calendar). + + + + + + If BC was not specified, and if the year field was two digits in length, then + adjust the year to 4 digits. If the field was less than 70, then add 2000; + otherwise, add 1900. + + + + + + + + History + + + + Contributed by + José Soares. + + + + + The Julian Day invented by the French scholar + Joseph Justus Scaliger (1540-1609) + and which probably takes its name from the Scaliger's father, + the Italian scholar Julius Caesar Scaliger (1484-1558). + Astronomers have used the Julian period to assign a unique number to + every day since 1 January 4713 BC. This is the so-called Julian Day + (JD). JD 0 designates the 24 hours from noon UTC on 1 January 4713 BC + to noon UTC on 2 January 4713 BC. + + + + Julian Day is different from Julian Date. + + The Julian calendar was introduced by Julius Caesar in 45 BC. It was + in common use until the 1582, when countries started changing to the + Gregorian calendar. + + In the Julian calendar, the tropical year is approximated as 365 1/4 + days = 365.25 days. This gives an error of 1 day in approximately + 128 days. + The accumulating calendar error prompted pope Gregory XIII + to reform the calendar in accordance with instructions + from the Council of Trent. + + + + In the Gregorian calendar, the tropical year is approximated as + 365 + 97 / 400 days = 365.2425 days. Thus it takes approximately 3300 + years for the tropical year to shift one day with respect to the + Gregorian calendar. + + + + The approximation 365+97/400 is achieved by having 97 leap years + every 400 years, using the following rules: + + + Every year divisible by 4 is a leap year. + + However, every year divisible by 100 is not a leap year. + + However, every year divisible by 400 is a leap year after all. + + -So, 1700, 1800, 1900, 2100, and 2200 are not leap years. But 1600, -2000, and 2400 are leap years. + So, 1700, 1800, 1900, 2100, and 2200 are not leap years. But 1600, + 2000, and 2400 are leap years. -instead in the Julian calendar only years divisible by 4 are leap years. + By contrast, in the older Julian calendar only years divisible by 4 are leap years. + -The papal bull of February 1582 decreed that 10 days should be dropped -from October 1582 so that 15 October should follow immediately after -4 October. -This was observed in Italy, Poland, Portugal, and Spain. Other Catholic -countries followed shortly after, but Protestant countries were -reluctant to change, and the Greek orthodox countries didn't change -until the start of this century. + + The papal bull of February 1582 decreed that 10 days should be dropped + from October 1582 so that 15 October should follow immediately after + 4 October. + This was observed in Italy, Poland, Portugal, and Spain. Other Catholic + countries followed shortly after, but Protestant countries were + reluctant to change, and the Greek orthodox countries didn't change + until the start of this century. -The reform was observed by Great Britain and Dominions (including what is -now the USA) -in 1752. -The 2 Sep 1752 was followed by 14 Sep 1752. + The reform was observed by Great Britain and Dominions (including what is + now the USA) in 1752. + Thus 2 Sep 1752 was followed by 14 Sep 1752. -This is why unix has the cal 9 1752 like this: + This is why Unix systems have cal + produce the following: + + +% cal 9 1752 September 1752 S M Tu W Th F S - 1 2 14 15 16 + 1 2 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 + + -My question is: -^^^^^^^^^^^^ - -If SQL92 says: - - (Second Informal Review Draft) ISO/IEC 9075:1992, Database - Language SQL- July 30, 1992 - -5.3 literals - 22)Within the definition of a , the s are constrained by the natural rules for dates and -times - according to the Gregorian calendar. - ^^^^^^^^^^^^^^^ - -Dates between 1752-09-03 and 1752-09-13. -Are they valid dates? -^^^^^^^^^^^^^^^^ - -> They have the nice property of correctly -> predicting/calculating any date more recent than something like 4013BC -> to far into the future, using the assumption that the length of the -> year is 365.25 days. This is a very recently adopted convention -> (sometime in the 1800s I had thought, but perhaps it was during the -> same "reform" in 1752). -> -> I've toyed with the idea of implementing a Chinese dynastic calendar, -> since it seems to be more predictable than historical European -> calendars. - -People's Republic of China uses the Gregorian calendar -for civil purposes. Chinese calendar is used for determining -festivals. - -The beginnings of the Chinese calendar can be traced back to the 14th -century BC. Legend has it that the Emperor Huangdi invented the -calendar in 2637 B - -José + + + SQL92 states that + Within the definition of a datetime literal, + the datetime values are constrained by the + natural rules for dates and times + according to the Gregorian calendar. + Dates between 1752-09-03 and 1752-09-13, although eliminated in + some countries by Papal fiat, conform to + natural rules and are hence valid dates. + + + + Different calendars have been developed in various parts of the + world, many predating the Gregorian system. + For example, + the beginnings of the Chinese calendar can be traced back to the 14th + century BC. Legend has it that the Emperor Huangdi invented the + calendar in 2637 BC. + + The People's Republic of China uses the Gregorian calendar + for civil purposes. Chinese calendar is used for determining + festivals. + + + + diff --git a/doc/src/sgml/pg_options.sgml b/doc/src/sgml/pg_options.sgml index a95cf03f25..15ac35f65f 100644 --- a/doc/src/sgml/pg_options.sgml +++ b/doc/src/sgml/pg_options.sgml @@ -1,4 +1,4 @@ - + diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index 1db1f03dea..1e81c5fa38 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -1,11 +1,15 @@ &biblio; diff --git a/doc/src/sgml/programmer.sgml b/doc/src/sgml/programmer.sgml index c29876f369..b099bdf176 100644 --- a/doc/src/sgml/programmer.sgml +++ b/doc/src/sgml/programmer.sgml @@ -1,10 +1,14 @@ + &cvs; &docguide; diff --git a/doc/src/sgml/xoper.sgml b/doc/src/sgml/xoper.sgml index 4ee4ac99e2..195acb4714 100644 --- a/doc/src/sgml/xoper.sgml +++ b/doc/src/sgml/xoper.sgml @@ -186,7 +186,7 @@ SELECT (a + b) AS c FROM test_complex; Providing NEGATOR is very helpful to the query optimizer since it allows expressions like NOT (x = y) to be simplified into - x <> y. This comes up more often than you might think, because + x <> y. This comes up more often than you might think, because NOTs can be inserted as a consequence of other rearrangements. @@ -225,21 +225,21 @@ SELECT (a + b) AS c FROM test_complex; These are the standard restriction estimators: eqsel for = - neqsel for <> - intltsel for < or <= - intgtsel for > or >= + neqsel for <> + intltsel for < or <= + intgtsel for > or >= It might seem a little odd that these are the categories, but they make sense if you think about it. '=' will typically accept only - a small fraction of the rows in a table; '<>' will typically reject - only a small fraction. '<' will accept a fraction that depends on + a small fraction of the rows in a table; '<>' will typically reject + only a small fraction. '<' will accept a fraction that depends on where the given constant falls in the range of values for that table column (which, it just so happens, is information collected by VACUUM ANALYZE and made available to the selectivity estimator). - '<=' will accept a slightly larger fraction than '<' for the same + '<=' will accept a slightly larger fraction than '<' for the same comparison constant, but they're close enough to not be worth distinguishing, especially since we're not likely to do better than a - rough guess anyhow. Similar remarks apply to '>' and '>='. + rough guess anyhow. Similar remarks apply to '>' and '>='. @@ -249,48 +249,48 @@ SELECT (a + b) AS c FROM test_complex; matching operators (~, ~*, etc) use eqsel on the assumption that they'll usually only match a small fraction of the entries in a table. + - - JOIN + + JOIN - - The JOIN clause, if provided, names a join selectivity - estimation function for the operator (note that this is a function - name, not an operator name). JOIN clauses only make sense for - binary operators that return boolean. The idea behind a join - selectivity estimator is to guess what fraction of the rows in a - pair of tables will satisfy a WHERE-clause condition of the form - + + The JOIN clause, if provided, names a join selectivity + estimation function for the operator (note that this is a function + name, not an operator name). JOIN clauses only make sense for + binary operators that return boolean. The idea behind a join + selectivity estimator is to guess what fraction of the rows in a + pair of tables will satisfy a WHERE-clause condition of the form + table1.field1 OP table2.field2 - - for the current operator. As with the RESTRICT clause, this helps - the optimizer very substantially by letting it figure out which - of several possible join sequences is likely to take the least work. - + + for the current operator. As with the RESTRICT clause, this helps + the optimizer very substantially by letting it figure out which + of several possible join sequences is likely to take the least work. + - - As before, this chapter will make no attempt to explain how to write - a join selectivity estimator function, but will just suggest that - you use one of the standard estimators if one is applicable: - + + As before, this chapter will make no attempt to explain how to write + a join selectivity estimator function, but will just suggest that + you use one of the standard estimators if one is applicable: + eqjoinsel for = - neqjoinsel for <> - intltjoinsel for < or <= - intgtjoinsel for > or >= - - + neqjoinsel for <> + intltjoinsel for < or <= + intgtjoinsel for > or >= + + + - + + HASHES - - HASHES - - - The HASHES clause, if present, tells the system that it is OK to - use the hash join method for a join based on this operator. HASHES - only makes sense for binary operators that return boolean --- and - in practice, the operator had better be equality for some data type. - + + The HASHES clause, if present, tells the system that it is OK to + use the hash join method for a join based on this operator. HASHES + only makes sense for binary operators that return boolean --- and + in practice, the operator had better be equality for some data type. + The assumption underlying hash join is that the join operator can