From 654f8f0b51c0860e17f025dbe8770bf0f8722697 Mon Sep 17 00:00:00 2001 From: "Thomas G. Lockhart" Date: Sat, 22 May 1999 02:27:25 +0000 Subject: 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 | 1533 +++++++++++++++++------------------------- doc/src/sgml/datetime.sgml | 834 +++++++++++++++++++---- 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, 1380 insertions(+), 1114 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/cvs.sgml b/doc/src/sgml/cvs.sgml index 74be5e13bde..aadf0027faa 100644 --- a/doc/src/sgml/cvs.sgml +++ b/doc/src/sgml/cvs.sgml @@ -1,9 +1,13 @@ - - - - -Marc -Fournier - - -1998-12-01 - - - The <productname>Postgres</productname> <productname>CVS</productname> Repository + + + + + Marc + Fournier + + + Tom + Lane + + + Thomas + Lockhart + + + 1999-05-20 + + + 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> - - -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. - - - -Anonymous CVS - - - -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). - - - - - -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: - + + + while inside of it, the patch is applied to the branch and + only the branch. + + + + + Getting The Source Via Anonymous <productname>CVS</productname> + + + 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. + + + + Anonymous CVS + + + + 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. + + + + + + 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. - - - - -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. - - - - - -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. - - + + + 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. + + + - - -You can save yourself some typing by making a file .cvsrc -in your home directory that contains + + 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. + + + + + + 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. + + + + + + + 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. + + -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. - - - - - - -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> - - -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. - - - -Installation from Binaries - - -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. - - - - -Retrieve the binary tar file appropriate for your platform. - - - - -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, - - - - - - - - - - - - -Installation from Binaries - - -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. - - - -Client Configuration - - - - - -Background - - - -Author - -Written by John Polstra, the -CVSup author. - - -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: - - http://www.research.digital.com/SRC/modula-3/html/platforms.html - -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. - -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. - -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. - -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. - -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. - -If I can answer any questions about CVSup or Modula-3, feel free -to contact me. - -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 - - - - -Installing <productname>CVSup</productname> - - -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. - - - -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. - - - -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 - - -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. - - -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 + + 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/. + + -Tom, + + Getting The Source Via <productname>CVSup</productname> -> We are starting to try to set up CVSup to support the PostgreSQL -> project. + + 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. + -Great! If I can help, just let me know. + + 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. + -> After being delayed while buying more disk to install Modula-3, + + Preparing A <productname>CVSup</productname> Client System + + + 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. + + + + 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 + + +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: + + +$ cvs init + + + after which you should see at least a directory named + CVSROOT when listing the + CVSROOT directory: + + +$ ls $CVSROOT +CVSROOT/ + + + + + + Running a <productname>CVSup</productname> Client + + + Verify that + cvsup is in your path; on most systems + you can do this by typing + + +which cvsup + + + Then, simply run + cvsup using: + + +$ cvsup -L 2 postgres.cvsup + + + 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. + + + + Here is a CVSup configuration file + modified for a specific installation, and which maintains a full + local CVS repository: + + +# 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 -:-} +# 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 -> 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 +# prefix directory points to where CVSup will store the actual distribution(s) +*default prefix=/home/cvs -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": +# complete distribution, including all below +pgsql - suptcp - suplib - server - client +# individual distributions vs 'the whole thing' +# pgsql-doc +# pgsql-perl5 +# pgsql-src -If all goes well, the executables will get created in the -subdirectories "server/LINUXELF" and "client/LINUXELF". + + -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. + + The following is a suggested CVSup config file from + the Postgres ftp site + which will fetch the current snapshot only: -John + +# 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=. -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 +# base directory points to where CVSup will store its 'bookmarks' file(s) +*default base=/usr/local/pgsql +# prefix directory points to where CVSup will store the actual distribution(s) +*default prefix=/usr/local/pgsql + +# complete distribution, including all below +pgsql + +# individual distributions vs 'the whole thing' +# pgsql-doc +# pgsql-perl5 +# pgsql-src + + + + + + + Installing <productname>CVSup</productname> + + + 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. + + + + <productname>CVSup</productname> Installation from Binaries + + + 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. + + + + 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. + + + + + + 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. + + + + + + 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, + + + + + + + + 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. + + + + + + If the binary is in the top level of the tar file, then simply + unpack the tar file into your target directory: + + +$ cd /usr/local/bin +$ tar zxvf /usr/local/src/cvsup-16.0-linux-i386.tar.gz +$ mv cvsup.1 ../doc/man/man1/ + + + + + + + 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. + + + + + + + + Ensure that the new binaries are in your path. + + +$ 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 + + + + + + + + + -instead in the Julian calendar only years divisible by 4 are leap years. + + Date/Time Support -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. + + Time Zones -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. + + + <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. + + + -This is why unix has the cal 9 1752 like this: - September 1752 - S M Tu W Th F S - 1 2 14 15 16 -17 18 19 20 21 22 23 -24 25 26 27 28 29 30 + + Australian time zones and their naming variants + account for fully one quarter of all time zones in the + Postgres time zone lookup table. + + + + Date/Time Input Interpretation + + + The date/time types are all decoded using a common set of routines. + + + + + Break the input string into tokens and categorize each token as + a string, time, time zone, or number. + + + + + + If the token contains a colon (":"), this is a time string. + + + + + + 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. + + -My question is: -^^^^^^^^^^^^ + + + 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 SQL92 says: + + + 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. + + - (Second Informal Review Draft) ISO/IEC 9075:1992, Database - Language SQL- July 30, 1992 + + + Otherwise, interpret as a year. + + + + -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. - ^^^^^^^^^^^^^^^ + + + If BC has been specified, negate the year and offset by one + (there is no year zero in the Gregorian calendar). + + -Dates between 1752-09-03 and 1752-09-13. -Are they valid dates? -^^^^^^^^^^^^^^^^ + + + 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. + + + + + -> 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. + + History -People's Republic of China uses the Gregorian calendar -for civil purposes. Chinese calendar is used for determining -festivals. + + + Contributed by + José Soares. + + -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 + + 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. + + 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 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 systems have cal + produce the following: + + +% cal 9 1752 + September 1752 + S M Tu W Th F S + 1 2 14 15 16 +17 18 19 20 21 22 23 +24 25 26 27 28 29 30 + + -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 a95cf03f258..15ac35f65fb 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 1db1f03dea0..1e81c5fa387 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 c29876f369c..b099bdf1765 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 4ee4ac99e20..195acb4714a 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 -- cgit v1.2.3