diff options
| author | Thomas G. Lockhart <lockhart@fourpalms.org> | 2000-03-30 22:22:41 +0000 |
|---|---|---|
| committer | Thomas G. Lockhart <lockhart@fourpalms.org> | 2000-03-30 22:22:41 +0000 |
| commit | f75bf1877ac7ccb297c1a960534a0178b3ac8f96 (patch) | |
| tree | 1465a377f4fc72afef4f644a96722f1156811247 /doc/src | |
| parent | 2cc8e6ac1fdac25181aca764afa813712c4c7e4e (diff) | |
Accumulated fixups.
Add some chapters on new topics.
Change to referencing OASIS/Docbook v3.1 rather than Davenport/Docbook v3.0
Grepped for and fixed apparent tag mangling from emacs
"Normalize" operation. Should be the last of those.
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/admin.sgml | 10 | ||||
| -rw-r--r-- | doc/src/sgml/advanced.sgml | 4 | ||||
| -rw-r--r-- | doc/src/sgml/bug-reporting.sgml | 296 | ||||
| -rw-r--r-- | doc/src/sgml/ecpg.sgml | 1937 | ||||
| -rw-r--r-- | doc/src/sgml/func.sgml | 4 | ||||
| -rw-r--r-- | doc/src/sgml/indices.sgml | 4 | ||||
| -rw-r--r-- | doc/src/sgml/installation.sgml | 11 | ||||
| -rw-r--r-- | doc/src/sgml/intro-ag.sgml | 5 | ||||
| -rw-r--r-- | doc/src/sgml/intro-pg.sgml | 5 | ||||
| -rw-r--r-- | doc/src/sgml/intro.sgml | 2 | ||||
| -rw-r--r-- | doc/src/sgml/jdbc.sgml | 4 | ||||
| -rw-r--r-- | doc/src/sgml/libpgtcl.sgml | 10 | ||||
| -rw-r--r-- | doc/src/sgml/plan.sgml | 263 | ||||
| -rw-r--r-- | doc/src/sgml/postgres.sgml | 172 | ||||
| -rw-r--r-- | doc/src/sgml/programmer.sgml | 86 | ||||
| -rw-r--r-- | doc/src/sgml/refentry.sgml | 2 | ||||
| -rw-r--r-- | doc/src/sgml/reference.sgml | 11 | ||||
| -rw-r--r-- | doc/src/sgml/tutorial.sgml | 1 | ||||
| -rw-r--r-- | doc/src/sgml/user.sgml | 58 |
19 files changed, 1475 insertions, 1410 deletions
diff --git a/doc/src/sgml/admin.sgml b/doc/src/sgml/admin.sgml index 4c33426a9d9..b69d9f759f1 100644 --- a/doc/src/sgml/admin.sgml +++ b/doc/src/sgml/admin.sgml @@ -1,11 +1,18 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.19 2000/03/28 14:16:06 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.20 2000/03/30 22:22:40 thomas Exp $ Postgres Administrator's Guide. Derived from postgres.sgml. - thomas 1998-10-27 $Log: admin.sgml,v $ +Revision 1.20 2000/03/30 22:22:40 thomas +Accumulated fixups. +Add some chapters on new topics. +Change to referencing OASIS/Docbook v3.1 rather than Davenport/Docbook v3.0 +Grepped for and fixed apparent tag mangling from emacs + "Normalize" operation. Should be the last of those. + Revision 1.19 2000/03/28 14:16:06 thomas Update SGML catalog references to DocBook 3.1 on FreeBSD. Matches postgresql.org/hub.org environment. @@ -34,6 +41,7 @@ Clean out duplicate stuff in odbc.sgml resulting from a faulty patch. <!entity info SYSTEM "info.sgml"> <!entity legal SYSTEM "legal.sgml"> <!entity notation SYSTEM "notation.sgml"> +<!entity problems SYSTEM "problems.sgml"> <!entity y2k SYSTEM "y2k.sgml"> <!entity config SYSTEM "config.sgml"> diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml index 8a5e6121068..eb60f91c7a4 100644 --- a/doc/src/sgml/advanced.sgml +++ b/doc/src/sgml/advanced.sgml @@ -3,7 +3,7 @@ <para> Having covered the basics of using - <productname>e>Postgr</productname>e> <acronym>SQL</acronym> to + <productname>Postgres</productname> <acronym>SQL</acronym> to access your data, we will now discuss those features of <productname>Postgres</productname> that distinguish it from conventional data managers. These features include inheritance, time @@ -103,7 +103,7 @@ SELECT c.name, c.altitude be run over cities and all classes below cities in the inheritance hierarchy. Many of the commands that we have already discussed (<command>select</command>, - <command>and>up</command>and> and <command>delete</command>) + <command>update</command> and <command>delete</command>) support this <quote>*</quote> notation, as do others, like <command>alter</command>. </para> diff --git a/doc/src/sgml/bug-reporting.sgml b/doc/src/sgml/bug-reporting.sgml deleted file mode 100644 index 2360fe64a33..00000000000 --- a/doc/src/sgml/bug-reporting.sgml +++ /dev/null @@ -1,296 +0,0 @@ -<Sect1> - <title>Bug Reporting Guidelines</title> - - <para> - When you encounter a bug in <productname>PostgreSQL</productname> we want to - hear about it. Your bug reports are an important part in making - <productname>PostgreSQL</productname> more reliable because even the utmost - care cannot guarantee that every part of PostgreSQL will work on every - platform under every circumstance. - </para> - - <para> - The following suggestions are intended to assist you in forming bug reports - that can be handled in an effective fashion. No one is required to follow - them but it tends to be to everyone's advantage. - </para> - - <para> - We cannot promise to fix every bug right away. If the bug is obvious, critical, - or affects a lot of users, chances are good that someone will look into it. It - could also happen that we tell you to update to a newer version to see if the - bug happens there. Or we might decide that the bug - cannot be fixed before some major rewrite we might be planning is done. Or - perhaps it's simply too hard and there are more important things on the agenda. - If you need help immediately, consider obtaining a commercial support contract. - </para> - - <Sect2> - <title>Identifying Bugs</title> - - <para> - Before you ask <quote>Is this a bug?</quote>, please read and re-read the - documentation to verify that you can really do whatever it is you are - trying. If it is not clear from the documentation whether you can do - something or not, please report that too, it's a bug in the documentation. - If it turns out that the program does something different from what the - documentation says, that's a bug. That might include, but is not limited to, - the following circumstances: - - <itemizedlist> - <listitem> - <para> - A program terminates with a fatal signal or an operating system - error message that would point to a problem in the program (for - example not <quote>disk full</quote>). - </para> - </listitem> - - <listitem> - <para> - A program produces the wrong output for any given input. - </para> - </listitem> - - <listitem> - <para> - A program refuses to accept valid input. - </para> - </listitem> - - <listitem> - <para> - A program accepts invalid input without a notice or error message. - </para> - </listitem> - - <listitem> - <para> - <productname>PostgreSQL</productname> fails to compile, build, or - install according to the instructions on supported platforms. - </para> - </listitem> - </itemizedlist> - - Here <quote>program</quote> refers to any executable, not only the backend server. - </para> - - <para> - Being slow or resource-hogging is not necessarily a bug. Read the documentation - or ask on one of the mailing lists for help in tuning your applications. Failing - to comply to <acronym>SQL</acronym> is not a bug unless compliance for the - specific feature is explicitly claimed. - </para> - - <para> - Before you continue, check on the TODO list and in the FAQ to see if your bug is - already known. If you can't decode the information on the TODO list, report your - problem. The least we can do is make the TODO list clearer. - </para> - </Sect2> - - <Sect2> - <title>What to report</title> - - <para> - The most important thing to remember about bug reporting is to state all - the facts and only facts. Do not speculate what you think went wrong, what - <quote>it seemed to do</quote>, or which part of the program has a fault. - If you are not familiar with the implementation you would probably guess - wrong and not help us a bit. And even if you are, educated explanations are - a great supplement to but no substitute for facts. If we are going to fix - the bug we still have to see it happen for ourselves first. - Reporting the bare facts - is relatively straightforward (you can probably copy and paste them from the - screen) but all too often important details are left out because someone - thought it doesn't matter or the report would <quote>ring a bell</quote> - anyway. - </para> - - <para> - The following items should be contained in every bug report: - - <itemizedlist> - <listitem> - <para> - The exact sequence of steps <emphasis>from program startup</emphasis> - necessary to reproduce the problem. This should be self-contained; - it is not enough to send in a bare select statement without the - preceeding create table and insert statements, if the output should - depend on the data in the tables. We do not have the time - to decode your database schema, and if we are supposed to make up - our own data we would probably miss the problem. - The best format for a test case for - query-language related problems is a file that can be run through the - <application>psql</application> frontend - that shows the problem. (Be sure to not have anything in your - <filename>~/.psqlrc</filename> startup file.) You are encouraged to - minimize the size of your example, but this is not absolutely necessary. - If the bug is reproduceable, we'll find it either way. - </para> - <para> - If your application uses some other client interface, such as PHP, then - please try to isolate the offending queries. We probably won't set up a - web server to reproduce your problem. In any case remember to provide - the exact input files, do not guess that the problem happens for - <quote>large files</quote> or <quote>mid-size databases</quote>, etc. - </para> - </listitem> - - <listitem> - <para> - The output you got. Please do not say that it <quote>didn't work</quote> or - <quote>failed</quote>. If there is an error message, - show it, even if you don't understand it. If the program terminates with - an operating system error, say which. If nothing at all happens, say so. - Even if the result of your test case is a program crash or otherwise obvious - it might not happen on our platform. The easiest thing is to copy the output - from the terminal, if possible. - </para> - <note> - <para> - In case of fatal errors, the error message provided by the client might - not contain all the information available. In that case, also look at the - output of the database server. If you do not keep your server output, - this would be a good time to start doing so. - </para> - </note> - </listitem> - - <listitem> - <para> - The output you expected is very important to state. If you just write - <quote>This command gives me that output.</quote> or <quote>This is not - what I expected.</quote>, we might run it ourselves, scan the output, and - think it looks okay and is exactly what we expected. We shouldn't have to - spend the time to decode the exact semantics behind your commands. - Especially refrain from merely saying that <quote>This is not what SQL says/Oracle - does.</quote> Digging out the correct behavior from <acronym>SQL</acronym> - is not a fun undertaking, nor do we all know how all the other relational - databases out there behave. (If your problem is a program crash you can - obviously omit this item.) - </para> - </listitem> - - <listitem> - <para> - Any command line options and other startup options, including concerned - environment variables or configuration files that you changed from the - default. Again, be exact. If you are using a pre-packaged - distribution that starts the database server at boot time, you should try - to find out how that is done. - </para> - </listitem> - - <listitem> - <para> - Anything you did at all differently from the installation instructions. - </para> - </listitem> - - <listitem> - <para> - The PostgreSQL version. You can run the command - <literal>SELECT version();</literal> to - find out. If this function does not exist, say so, then we know that - your version is old enough. If you can't start up the server or a - client, look into the README file in the source directory or at the - name of your distribution file or package name. If your version is older - than 6.5 we will almost certainly tell you to upgrade. There are tons - of bugs in old versions, that's why we write new ones. - </para> - <para> - If you run a pre-packaged version, such as RPMs, say so, including any - subversion the package may have. If you are talking about a CVS - snapshot, mention that, including its date and time. - </para> - </listitem> - - <listitem> - <para> - Platform information. This includes the kernel name and version, C library, - processor, memory information. In most cases it is sufficient to report - the vendor and version, but do not assume everyone knows what exactly - <quote>Debian</quote> contains or that everyone runs on Pentiums. If - you have installation problems information about compilers, make, etc. - is also necessary. - </para> - </listitem> - </itemizedlist> - - Do not be afraid if your bug report becomes rather lengthy. That is a fact of life. - It's better to report everything the first time than us having to squeeze the - facts out of you. On the other hand, if your input files are huge, it is - fair to ask first whether somebody is interested in looking into it. - </para> - - <para> - Do not spend all your time to figure out which changes in the input make - the problem go away. This will probably not help solving it. If it turns - out that the bug can't be fixed right away, you will still have time to - find and share your work around. Also, once again, do not waste your time - guessing why the bug exists. We'll find that out soon enough. - </para> - - <para> - When writing a bug report, please choose non-confusing terminology. - The software package as such is called <quote>PostgreSQL</quote>, - sometimes <quote>Postgres</quote> for short. (Sometimes - the abbreviation <quote>Pgsql</quote> is used but don't do that.) When you - are specifically talking about the backend server, mention that, don't - just say <quote>Postgres crashes</quote>. The interactive frontend is called - <quote>psql</quote> and is for all intends and purposes completely separate - from the backend. - </para> - </Sect2> - - <Sect2> - <title>Where to report bugs</title> - - <para> - In general, send bug reports to <pgsql-bugs@postgresql.org>. You are - invited to find a descriptive subject for your email message, perhaps parts - of the error message. - </para> - - <para> - Do not send bug reports to any of the user mailing lists, such as - pgsql-sql or pgsql-general. These mailing lists are for answering - user questions, their subscribers normally do not wish to receive - bug reports. More importantly, they are unlikely to fix them. - </para> - - <para> - Also, please do <emphasis>not</emphasis> send reports to - <pgsql-hackers@postgresql.org>. This list is for discussing the - development of <productname>PostgreSQL</productname>, it would be nice - if we could keep the bug reports separate. We might choose take up a - discussion - about your bug report on it, if the bug needs more review. - </para> - - <para> - If you have a problem with the documentation, send email to - <pgsql-docs@postgresql.org>. Refer to the document, chapter, and sections. - </para> - - <para> - If your bug is a portability problem on a non-supported platform, send - mail to <pgsql-ports@postgresql.org>, so we (and you) can work on - porting <productname>PostgreSQL</productname> to your platform. - </para> - - <note> - <para> - Due to the unfortunate amount of spam going around, all of the above - email addresses are closed mailing lists. That is, you need to be - subscribed to them in order to be allowed to post. If you simply - want to send mail but do not want to receive list traffic, you can - subscribe to the special pgsql-loophole <quote>list</quote>, which - allows you to post to all <productname>PostgreSQL</productname> - mailing lists without receiving any messages. Send email to - <pgsql-loophole-request@postgresql.org> to subscribe. - </para> - </note> - </Sect2> -</Sect1> diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml index 7f0f785d4b6..75ef0b128c5 100644 --- a/doc/src/sgml/ecpg.sgml +++ b/doc/src/sgml/ecpg.sgml @@ -1,180 +1,182 @@ -<Chapter Id="ecpg"> -<DocInfo> -<AuthorGroup> -<Author> -<FirstName>Linus</FirstName> -<Surname>Tolke</Surname> -</Author> -<Author> -<FirstName>Michael</FirstName> -<Surname>Meskes</Surname> -</Author> -</AuthorGroup> -<Copyright> -<Year>1996-1997</Year> -<Holder>Linus Tolke</Holder> -</Copyright> -<Copyright> -<Year>1998</Year> -<Holder>Michael Meskes</Holder> -</Copyright> -<Date>Transcribed 1998-02-12</Date> -</DocInfo> - -<Title><Application>ecpg</Application> - Embedded <Acronym>SQL</Acronym> -in <Acronym>C</Acronym></Title> - -<Para> -This describes an embedded <Acronym>SQL</Acronym> in <Acronym>C</Acronym> -package for <ProductName>Postgres</ProductName>. - -It is written by <ULink url="mailto:linus@epact.se">Linus Tolke</ULink> -and <ULink url="mailto:meskes@postgresql.org">Michael Meskes</ULink>. - -<Note> -<Para> -Permission is granted to copy and use in the same way as you are allowed -to copy and use the rest of the <ProductName>PostgreSQL</ProductName>. -</Para> -</Note> -</para> -<Sect1> -<Title>Why Embedded <Acronym>SQL</Acronym>?</Title> - -<Para> -Embedded <Acronym>SQL</Acronym> has some small advantages over other ways -to handle <Acronym>SQL</Acronym> -queries. It takes care of all the tedious moving of information to and -from variables in your <Acronym>C</Acronym> program. -Many <Acronym>RDBMS</Acronym> packages -support this embedded language. -</Para> - -<Para> There is an ANSI-standard describing how the embedded language should -work. <Application>ecpg</Application> was designed to meet this standard -as much as possible. So it is -possible to port programs with embedded <Acronym>SQL</Acronym> written for -other <Acronym>RDBMS</Acronym> packages to -<ProductName>Postgres</ProductName> and thus promoting the spirit of free -software. -</Para> -</sect1> -<Sect1> -<Title>The Concept</Title> - -<Para> -You write your program in <Acronym>C</Acronym> with some -special <Acronym>SQL</Acronym> things. -For declaring variables that can be used in -<Acronym>SQL</Acronym> statements you need to -put them in a special declare section. -You use a special syntax for the <Acronym>SQL</Acronym> queries. -</Para> - -<Para> -Before compiling you run the file through -the embedded <Acronym>SQL</Acronym> <Acronym>C</Acronym> -preprocessor and it converts the <Acronym>SQL</Acronym> statements you used -to function -calls with the variables used as arguments. Both variables that are used -as input to the <Acronym>SQL</Acronym> statements and variables that will -contain the -result are passed. -</Para> - -<Para> -Then you compile and at link time you link with a special library that -contains the functions used. These functions (actually it is mostly one -single function) fetches the information from the arguments, performs -the <Acronym>SQL</Acronym> query using the ordinary interface -(<FileName>libpq</FileName>) and puts back -the result in the arguments dedicated for output. -</Para> - -<Para> -Then you run your program and when the control arrives to -the <Acronym>SQL</Acronym> -statement the <Acronym>SQL</Acronym> statement is performed against -the database and you -can continue with the result. -</Para> -</sect1> - -<Sect1> -<Title>How To Use <Application>egpc</Application></Title> - -<Para> -This section describes how to use the <Application>egpc</Application> tool. -</Para> - -<Sect2> -<Title>Preprocessor</title> - -<Para> -The preprocessor is called <Application>ecpg</Application>. -After installation it resides in -the <ProductName>Postgres</ProductName> <FileName>bin/</FileName> directory. -</Para> -</sect2> -<Sect2> -<Title>Library</title> - -<Para> -The <Application>ecpg</Application> library is called -<FileName>libecpg.a</FileName> or -<FileName>libecpg.so</FileName>. Additionally, the library -uses the <FileName>libpq</FileName> library for communication to the -<ProductName>Postgres</ProductName> server so you will -have to link your program with <Parameter>-lecpg -lpq</Parameter>. -</Para> - -<Para> -The library has some methods that are "hidden" but that could prove very -useful sometime. - -<itemizedlist> -<listitem> -<para> -<function>ECPGdebug(int <replaceable class="parameter">on</replaceable>, FILE *<replaceable class="parameter">stream</replaceable>)</function> -turns on debug logging if called with the first argument non-zero. -Debug logging is done on <replaceable class="parameter">stream</replaceable>. - Most <Acronym>SQL</Acronym> statement logs its arguments and result. -</Para> - -<Para> -The most important one (<Function>ECPGdo</Function>) -that is called on almost all <Acronym>SQL</Acronym> -statements logs both its expanded string, - i.e. the string -with all the input variables inserted, and the result from the -<ProductName>Postgres</ProductName> server. - This can be very useful when searching for errors -in your <Acronym>SQL</Acronym> statements. -</Para> -</ListItem> - -<listitem> -<para> -<function>ECPGstatus()</function> -This method returns TRUE if we are connected to a database and FALSE if not. -</Para> -</ListItem> -</itemizedlist> -</Para> -</sect2> - -<Sect2> -<Title>Error handling</title> - -<Para> -To be able to detect errors from the <ProductName>Postgres</ProductName> -server you include a line like -<ProgramListing> -exec sql include sqlca; -</ProgramListing> -in the include section of your file. This will define a struct and a -variable with the name <Parameter>sqlca</Parameter> as following: -<ProgramListing> + <chapter> + <docinfo> + <authorgroup> + <author> + <firstname>Linus</firstname> + <surname>Tolke</surname> + </author> + <author> + <firstname>Michael</firstname> + <surname>Meskes</surname> + </author> + </authorgroup> + <copyright> + <year>1996-1997</year> + <holder>Linus Tolke</holder> + </copyright> + <copyright> + <year>1998</year> + <holder>Michael Meskes</holder> + </copyright> + <date>Transcribed 1998-02-12</date> + </docinfo> + + <title><application>ecpg</application> - Embedded <acronym>SQL</acronym> + in <acronym>C</acronym></title> + + <para> + This describes an embedded <acronym>SQL</acronym> in <acronym>C</acronym> + package for <productname>Postgres</productname>. + + It is written by <ulink url="">Linus Tolke</ulink> + and <ulink url="">Michael Meskes</ulink>. + + <note> + <para> + Permission is granted to copy and use in the same way as you are allowed + to copy and use the rest of the <productname>PostgreSQL</productname>. + </para> + </note> + </para> + <sect1> + <title>Why Embedded <acronym>SQL</acronym>?</title> + + <para> + Embedded <acronym>SQL</acronym> has some small advantages over other ways + to handle <acronym>SQL</acronym> + queries. It takes care of all the tedious moving of information to and + from variables in your <acronym>C</acronym> program. + Many <acronym>RDBMS</acronym> packages + support this embedded language. + </para> + + <para> There is an ANSI-standard describing how the embedded language should + work. <application>ecpg</application> was designed to meet this standard + as much as possible. So it is + possible to port programs with embedded <acronym>SQL</acronym> written for + other <acronym>RDBMS</acronym> packages to + <productname>Postgres</productname> and thus promoting the spirit of free + software. + </para> + </sect1> + + <sect1> + <title>The Concept</title> + + <para> + You write your program in <acronym>C</acronym> with some + special <acronym>SQL</acronym> things. + For declaring variables that can be used in + <acronym>SQL</acronym> statements you need to + put them in a special declare section. + You use a special syntax for the <acronym>SQL</acronym> queries. + </para> + + <para> + Before compiling you run the file through + the embedded <acronym>SQL</acronym> <acronym>C</acronym> + preprocessor and it converts the <acronym>SQL</acronym> statements you used + to function + calls with the variables used as arguments. Both variables that are used + as input to the <acronym>SQL</acronym> statements and variables that will + contain the + result are passed. + </para> + + <para> + Then you compile and at link time you link with a special library that + contains the functions used. These functions (actually it is mostly one + single function) fetches the information from the arguments, performs + the <acronym>SQL</acronym> query using the ordinary interface + (<filename>libpq</filename>) and puts back + the result in the arguments dedicated for output. + </para> + + <para> + Then you run your program and when the control arrives to + the <acronym>SQL</acronym> + statement the <acronym>SQL</acronym> statement is performed against + the database and you + can continue with the result. + </para> + </sect1> + + <sect1> + <title>How To Use <application>ecpg</application></title> + + <para> + This section describes how to use the <application>ecpg</application> tool. + </para> + + <sect2> + <title>Preprocessor</title> + + <para> + The preprocessor is called <application>ecpg</application>. + After installation it resides in + the <productname>Postgres</productname> <filename>bin/</filename> directory. + </para> + </sect2> + <sect2> + <title>Library</title> + + <para> + The <application>ecpg</application> library is called + <filename>libecpg.a</filename> or + <filename>libecpg.so</filename>. Additionally, the library + uses the <filename>libpq</filename> library for communication to the + <productname>Postgres</productname> server so you will + have to link your program with <parameter>-lecpg -lpq</parameter>. + </para> + + <para> + The library has some methods that are "hidden" but that could prove very + useful sometime. + + <itemizedlist> + <listitem> + <para> + <function>ECPGdebug(int <replaceable>on</replaceable>, FILE + *<replaceable>stream</replaceable>)</function> + turns on debug logging if called with the first argument non-zero. + Debug logging is done on <replaceable>stream</replaceable>. + Most <acronym>SQL</acronym> statement logs its arguments and result. + </para> + + <para> + The most important one (<function>ECPGdo</function>) + that is called on almost all <acronym>SQL</acronym> + statements logs both its expanded string, + i.e. the string + with all the input variables inserted, and the result from the + <productname>Postgres</productname> server. + This can be very useful when searching for errors + in your <acronym>SQL</acronym> statements. + </para> + </listitem> + + <listitem> + <para> + <function>ECPGstatus()</function> + This method returns TRUE if we are connected to a database and FALSE if not. + </para> + </listitem> + </itemizedlist> + </para> + </sect2> + + <sect2> + <title>Error handling</title> + + <para> + To be able to detect errors from the <productname>Postgres</productname> + server you include a line like + <programlisting> + exec sql include sqlca; + </programlisting> + in the include section of your file. This will define a struct and a + variable with the name <parameter>sqlca</parameter> as following: + <programlisting> struct sqlca { char sqlcaid[8]; @@ -207,702 +209,712 @@ struct sqlca /* 7: empty */ char sqlext[8]; } sqlca; -</ProgramListing> -</Para> - -<Para> -If an error occured in the last <Acronym>SQL</Acronym> statement -then <Parameter>sqlca.sqlcode</Parameter> -will be non-zero. If <Parameter>sqlca.sqlcode</Parameter> is less that 0 - then this is -some kind of serious error, like the database definition does not match -the query given. If it is bigger than 0 then this is a normal error like -the table did not contain the requested row. -</Para> - -<Para> -sqlca.sqlerrm.sqlerrmc will contain a string that describes the error. -The string ends with the line number -in the source file. -</Para> - -<Para> -List of errors that can occur: - -<VariableList> -<VarListEntry> -<Term>-12, Out of memory in line %d.</Term> -<ListItem> -<Para> -Does not normally occur. This is a sign that your virtual memory is -exhausted. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>-200, Unsupported type %s on line %d.</Term> -<ListItem> -<Para> -Does not normally occur. This is a sign that the preprocessor has -generated something that the library does not know about. Perhaps you -are running incompatible versions of the preprocessor and the library. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>-201, Too many arguments line %d.</Term> -<ListItem> -<Para> -This means that <ProductName>Postgres</ProductName> has returned more -arguments than we have -matching variables. Perhaps you have forgotten a couple of the host -variables in the <Command>INTO :var1,:var2</Command>-list. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>-202, Too few arguments line %d.</Term> -<ListItem> -<Para> -This means that <ProductName>Postgres</ProductName> has returned fewer -arguments than we have -host variables. Perhaps you have too many host variables in the -<Command>INTO :var1,:var2</Command>-list. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>-203, Too many matches line %d.</Term> -<ListItem> -<Para> -This means that the query has returned several lines but the -variables specified are no arrays. The <Command>SELECT</Command> you made -probably was not unique. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>-204, Not correctly formatted int type: %s line %d.</Term> -<ListItem> -<Para> -This means that the host variable is of an <Type>int</Type> type and the field -in the <ProductName>Postgres</ProductName> database is of another type and -contains a value that cannot be interpreted as an <Type>int</Type>. -The library uses <Function>strtol</Function> -for this conversion. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>-205, Not correctly formatted unsigned type: %s line %d.</Term> -<ListItem> -<Para> -This means that the host variable is of an <Type>unsigned int</Type> type and -the field in the <ProductName>Postgres</ProductName> database is of another -type and contains a -value that cannot be interpreted as an <Type>unsigned int</Type>. The library -uses <Function>strtoul</Function> for this conversion. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>-206, Not correctly formatted floating point type: %s line %d.</Term> -<ListItem> -<Para> -This means that the host variable is of a <Type>float</Type> type and -the field in the <ProductName>Postgres</ProductName> database is of another -type and contains a -value that cannot be interpreted as an <Type>float</Type>. The library -uses <Function>strtod</Function> for this conversion. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>-207, Unable to convert %s to bool on line %d.</Term> -<ListItem> -<Para> -This means that the host variable is of a <Type>bool</Type> type and -the field in the <ProductName>Postgres</ProductName> database is neither 't' -nor 'f'. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>-208, Empty query line %d.</Term> -<ListItem> -<Para> -<ProductName>Postgres</ProductName> returned PGRES_EMPTY_QUERY, probably -because the query indeed was empty. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>-220, No such connection %s in line %d.</Term> -<ListItem> -<Para> -The program tries to access a connection that does not exist. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>-221, Not connected in line %d.</Term> -<ListItem> -<Para> -The program tries to access a connection that does exist but is not open. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>-230, Invalid statement name %s in line %d.</Term> -<ListItem> -<Para> -The statement you are trying to use has not been prepared. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>-400, Postgres error: %s line %d.</Term> -<ListItem> -<Para> -Some <ProductName>Postgres</ProductName> error. -The message contains the error message from the -<ProductName>Postgres</ProductName> backend. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>-401, Error in transaction processing line %d. </Term> -<ListItem> -<Para> -<ProductName>Postgres</ProductName> signalled to us that we cannot start, -commit or rollback the transaction. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>-402, connect: could not open database %s.</Term> -<ListItem> -<Para> -The connect to the database did not work. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>100, Data not found line %d.</Term> -<ListItem> -<Para> -This is a "normal" error that tells you that what you are quering cannot -be found or we have gone through the cursor. -</Para> -</ListItem> -</VarListEntry> - -</VariableList> -</Para> -</Sect2> -</sect1> - -<Sect1> -<Title>Limitations</Title> - -<Para> -What will never be included and why or what cannot be done with this -concept. - -<VariableList> -<VarListEntry> -<Term>oracles single tasking possibility</Term> -<ListItem> -<Para> -Oracle version 7.0 on AIX 3 uses the OS-supported locks on the shared -memory segments and allows the application designer to link an -application in a so called single tasking way. Instead of starting one -client process per application process both the database part and the -application part is run in the same process. In later versions of oracle -this is no longer supported. -</Para> - -<Para> -This would require a total redesign of the <ProductName>Postgres</ProductName> access model and -that effort can not justify the performance gained. -</Para> -</ListItem> -</VarListEntry> -</VariableList> -</Para> -</sect1> - -<Sect1> -<Title>Porting From Other <Acronym>RDBMS</Acronym> Packages</Title> - -<Para> -The design of <Application>ecpg</Application> follows SQL standard. So -porting from a standard RDBMS should not be a problem. Unfortunately there -is no such thing as a standard RDBMS. So <Application>ecpg</Application> -also tries to understand syntax additions as long as they do not create -conflicts with the standard. -</Para> - -<Para> -The following list shows all the known incompatibilities. If you find one -not listed please notify <ULink url="mailto:meskes@postgresql.org">Michael -Meskes</ULink>. Note, however, that we list only incompatibilities from -a precompiler of another RDBMS to <Application>ecpg</Application> and not -additional <Application>ecpg</Application> features that these RDBMS do not -have. -</Para> - -<Para> -<VariableList> -<VarListEntry> -<Term>Syntax of FETCH command</Term> -<ListItem> -<Para> -The standard syntax of the FETCH command is: -</para> -<Para> -FETCH [direction] [amount] IN|FROM <Replaceable>cursor name</Replaceable>. -</Para> -<para> -<Application>ORACLE</Application>, however, does not use the keywords IN -resp. FROM. This feature cannot be added since it would create parsing -conflicts. -</Para> -</ListItem> -</VarListEntry> -</VariableList> -</Para> -</sect1> - -<Sect1> -<Title>Installation</Title> - -<Para> -Since version 0.5 <Application>ecpg</Application> is distributed -together with <ProductName>Postgres</ProductName>. So you -should get your precompiler, libraries and header files compiled and -installed by default as a part of your installation. -</Para> -</sect1> - -<Sect1> -<Title>For the Developer</Title> - -<Para> -This section is for those who want to develop the -<Application>ecpg</Application> interface. It -describes how the things work. The ambition is to make this section -contain things for those that want to have a look inside and the section -on How to use it should be enough for all normal questions. - -So, read this before looking at the internals of the -<Application>ecpg</Application>. If -you are not interested in how it really works, skip this section. -</Para> - -<Sect2> -<Title>ToDo List</Title> - -<Para> -This version the preprocessor has some flaws: - -<VariableList> -<VarListEntry> -<Term>Library functions</Term> -<ListItem> -<Para> -to_date et al. do not exists. But then <ProductName>Postgres</ProductName> -has some good conversion routines itself. So you probably won't miss these. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>Structures ans unions</Term> -<ListItem> -<Para> -Structures and unions have to be defined in the declare section. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>Missing statements</Term> -<ListItem> -<Para> -The following statements are not implemented thus far: -<VariableList> -<VarListEntry> -<Term> exec sql allocate</Term> -<ListItem> -<Para> -</Para> -</listitem> -</VarListEntry> -<VarListEntry> -<Term> exec sql deallocate</Term> -<ListItem> -<Para> -</Para> -</listitem> -</VarListEntry> -<VarListEntry> -<Term> SQLSTATE</Term> -<ListItem> -<Para> -</Para> -</listitem> -</VarListEntry> -</VariableList> -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>message 'no data found'</Term> -<ListItem> -<Para> -The error message for "no data" in an exec sql insert select from statement -has to be 100. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>sqlwarn[6]</Term> -<ListItem> -<Para> -sqlwarn[6] should be 'W' if the PRECISION or SCALE value specified in a SET -DESCRIPTOR statement will be ignored. -</Para> -</ListItem> -</VarListEntry> -</VariableList> -</Para> -</sect2> - -<Sect2> -<Title>The Preprocessor</Title> - -<Para> -The first four lines written to the output are constant additions by ecpg. -These are two comments and two include lines necessary for the interface to the -library. -</Para> - -<Para> -Then the preprocessor works in one pass only, reading the input file and -writing to the output as it goes along. Normally it just echoes -everything to the output without looking at it further. -</Para> - -<Para> -When it comes to an <Command>EXEC SQL</Command> statements it intervenes and -changes them depending on what it is. -The <Command>EXEC SQL</Command> statement can be one of these: - -<VariableList> -<VarListEntry> -<Term>Declare sections</Term> -<ListItem> -<Para> -Declare sections begins with -<ProgramListing> + </programlisting> + </para> + + <para> + If an error occured in the last <acronym>SQL</acronym> statement + then <parameter>sqlca.sqlcode</parameter> + will be non-zero. If <parameter>sqlca.sqlcode</parameter> is less that 0 + then this is + some kind of serious error, like the database definition does not match + the query given. If it is bigger than 0 then this is a normal error like + the table did not contain the requested row. + </para> + + <para> + sqlca.sqlerrm.sqlerrmc will contain a string that describes the error. + The string ends with the line number + in the source file. + </para> + + <para> + List of errors that can occur: + + <variablelist> + <varlistentry> + <term>-12, Out of memory in line %d.</term> + <listitem> + <para> + Does not normally occur. This is a sign that your virtual memory is + exhausted. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-200, Unsupported type %s on line %d.</term> + <listitem> + <para> + Does not normally occur. This is a sign that the preprocessor has + generated something that the library does not know about. Perhaps you + are running incompatible versions of the preprocessor and the library. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-201, Too many arguments line %d.</term> + <listitem> + <para> + This means that <productname>Postgres</productname> has returned more + arguments than we have + matching variables. Perhaps you have forgotten a couple of the host + variables in the <command>INTO :var1,:var2</command>-list. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-202, Too few arguments line %d.</term> + <listitem> + <para> + This means that <productname>Postgres</productname> has returned fewer + arguments than we have + host variables. Perhaps you have too many host variables in the + <command>INTO :var1,:var2</command>-list. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-203, Too many matches line %d.</term> + <listitem> + <para> + This means that the query has returned several lines but the + variables specified are no arrays. The <command>SELECT</command> you made + probably was not unique. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-204, Not correctly formatted int type: %s line %d.</term> + <listitem> + <para> + This means that the host variable is of an <type>int</type> type and the field + in the <productname>Postgres</productname> database is of another type and + contains a value that cannot be interpreted as an <type>int</type>. + The library uses <function>strtol</function> + for this conversion. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-205, Not correctly formatted unsigned type: %s line %d.</term> + <listitem> + <para> + This means that the host variable is of an <type>unsigned int</type> type and + the field in the <productname>Postgres</productname> database is of another + type and contains a + value that cannot be interpreted as an <type>unsigned int</type>. The library + uses <function>strtoul</function> for this conversion. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-206, Not correctly formatted floating point type: %s line %d.</term> + <listitem> + <para> + This means that the host variable is of a <type>float</type> type and + the field in the <productname>Postgres</productname> database is of another + type and contains a + value that cannot be interpreted as an <type>float</type>. The library + uses <function>strtod</function> for this conversion. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-207, Unable to convert %s to bool on line %d.</term> + <listitem> + <para> + This means that the host variable is of a <type>bool</type> type and + the field in the <productname>Postgres</productname> database is neither 't' + nor 'f'. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-208, Empty query line %d.</term> + <listitem> + <para> + <productname>Postgres</productname> returned PGRES_EMPTY_QUERY, probably + because the query indeed was empty. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-220, No such connection %s in line %d.</term> + <listitem> + <para> + The program tries to access a connection that does not exist. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-221, Not connected in line %d.</term> + <listitem> + <para> + The program tries to access a connection that does exist but is not open. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-230, Invalid statement name %s in line %d.</term> + <listitem> + <para> + The statement you are trying to use has not been prepared. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-400, Postgres error: %s line %d.</term> + <listitem> + <para> + Some <productname>Postgres</productname> error. + The message contains the error message from the + <productname>Postgres</productname> backend. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-401, Error in transaction processing line %d. </term> + <listitem> + <para> + <productname>Postgres</productname> signalled to us that we cannot start, + commit or rollback the transaction. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-402, connect: could not open database %s.</term> + <listitem> + <para> + The connect to the database did not work. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>100, Data not found line %d.</term> + <listitem> + <para> + This is a "normal" error that tells you that what you are quering cannot + be found or we have gone through the cursor. + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + </sect2> + </sect1> + + <sect1> + <title>Limitations</title> + + <abstract> + <para> + What will never be included and why or what cannot be done with this + concept. + </para> + </abstract> + + <para> + <variablelist> + <varlistentry> + <term>Oracle's single tasking possibility</term> + <listitem> + <para> + Oracle version 7.0 on AIX 3 uses the OS-supported locks on the shared + memory segments and allows the application designer to link an + application in a so called single tasking way. Instead of starting one + client process per application process both the database part and the + application part is run in the same process. In later versions of Oracle + this is no longer supported. + </para> + + <para> + This would require a total redesign of the + <productname>Postgres</productname> access model and + that effort can not justify the performance gained. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </sect1> + + <sect1> + <title>Porting From Other <acronym>RDBMS</acronym> Packages</title> + + <para> + The design of <application>ecpg</application> follows SQL standard. So + porting from a standard RDBMS should not be a problem. Unfortunately there + is no such thing as a standard RDBMS. So <application>ecpg</application> + also tries to understand syntax additions as long as they do not create + conflicts with the standard. + </para> + + <para> + The following list shows all the known incompatibilities. If you find one + not listed please notify <ulink url="">Michael + Meskes</ulink>. Note, however, that we list only incompatibilities from + a precompiler of another RDBMS to <application>ecpg</application> and not + additional <application>ecpg</application> features that these RDBMS do not + have. + </para> + + <para> + <variablelist> + <varlistentry> + <term>Syntax of FETCH command</term> + <listitem> + <para> + The standard syntax of the FETCH command is: + </para> + <para> + FETCH [direction] [amount] IN|FROM <replaceable>cursor name</replaceable>. + </para> + <para> + <application>ORACLE</application>, however, does not use the keywords IN + resp. FROM. This feature cannot be added since it would create parsing + conflicts. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </sect1> + + <sect1> + <title>Installation</title> + + <para> + Since version 0.5 <application>ecpg</application> is distributed + together with <productname>Postgres</productname>. So you + should get your precompiler, libraries and header files compiled and + installed by default as a part of your installation. + </para> + </sect1> + + <sect1> + <title>For the Developer</title> + + <para> + This section is for those who want to develop the + <application>ecpg</application> interface. It + describes how the things work. The ambition is to make this section + contain things for those that want to have a look inside and the section + on How to use it should be enough for all normal questions. + + So, read this before looking at the internals of the + <application>ecpg</application>. If + you are not interested in how it really works, skip this section. + </para> + + <sect2> + <title>ToDo List</title> + + <para> + This version the preprocessor has some flaws: + + <variablelist> + <varlistentry> + <term>Library functions</term> + <listitem> + <para> + to_date et al. do not exists. But then <productname>Postgres</productname> + has some good conversion routines itself. So you probably won't miss these. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Structures ans unions</term> + <listitem> + <para> + Structures and unions have to be defined in the declare section. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Missing statements</term> + <listitem> + <para> + The following statements are not implemented thus far: + <variablelist> + <varlistentry> + <term> exec sql allocate</term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> exec sql deallocate</term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> SQLSTATE</term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>message 'no data found'</term> + <listitem> + <para> + The error message for "no data" in an exec sql insert select from statement + has to be 100. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>sqlwarn[6]</term> + <listitem> + <para> + sqlwarn[6] should be 'W' if the PRECISION or SCALE value specified in a SET + DESCRIPTOR statement will be ignored. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </sect2> + + <sect2> + <title>The Preprocessor</title> + + <para> + The first four lines written to the output are constant additions by ecpg. + These are two comments and two include lines necessary for the interface to the + library. + </para> + + <para> + Then the preprocessor works in one pass only, reading the input file and + writing to the output as it goes along. Normally it just echoes + everything to the output without looking at it further. + </para> + + <para> + When it comes to an <command>EXEC SQL</command> statements it intervenes and + changes them depending on what it is. + The <command>EXEC SQL</command> statement can be one of these: + + <variablelist> + <varlistentry> + <term>Declare sections</term> + <listitem> + <para> + Declare sections begins with + <programlisting> exec sql begin declare section; -</ProgramListing> -and ends with -<ProgramListing> + </programlisting> + and ends with + <programlisting> exec sql end declare section; -</ProgramListing> -In the section only variable declarations are allowed. Every variable -declare within this section is also entered in a list of variables -indexed on their name together with the corresponding type. -</Para> - -<Para> -In particular the definition of a structure or union also has to be listed -inside a declare section. Otherwise <Application>ecpg</Application> cannot -handle these types since it simply does not know the definition. -</Para> - -<Para> -The declaration is echoed to the file to make the variable a normal -C-variable also. -</Para> - -<Para> -The special types VARCHAR and VARCHAR2 are converted into a named struct -for every variable. A declaration like: -<ProgramListing> + </programlisting> + In the section only variable declarations are allowed. Every variable + declare within this section is also entered in a list of variables + indexed on their name together with the corresponding type. + </para> + + <para> + In particular the definition of a structure or union also has to be listed + inside a declare section. Otherwise <application>ecpg</application> cannot + handle these types since it simply does not know the definition. + </para> + + <para> + The declaration is echoed to the file to make the variable a normal + C-variable also. + </para> + + <para> + The special types VARCHAR and VARCHAR2 are converted into a named struct + for every variable. A declaration like: + <programlisting> VARCHAR var[180]; -</ProgramListing> -is converted into -<ProgramListing> + </programlisting> + is converted into + <programlisting> struct varchar_var { int len; char arr[180]; } var; -</ProgramListing> -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>Include statements</Term> -<ListItem> -<Para> -An include statement looks like: -<ProgramListing> + </programlisting> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Include statements</term> + <listitem> + <para> + An include statement looks like: + <programlisting> exec sql include filename; -</ProgramListing> -Not that this is NOT the same as -<ProgramListing> + </programlisting> + Note that this is NOT the same as + <programlisting> #include <filename.h> -</ProgramListing> -</Para> - -<Para> -Instead the file specified is parsed by <Application>ecpg</Application> -itself. So the contents of the specified file is included in the resulting C -code. This way you are able to specify EXEC SQL commands in an include file. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>Connect statement</Term> -<ListItem> -<Para> -A connect statement looks like: -<ProgramListing> -exec sql connect to <Replaceable>connection target</Replaceable>; -</ProgramListing> -It creates a connection to the specified database. -</Para> - -<Para> -The <Replaceable>connection target</Replaceable> can be specified in the -following ways: -<VariableList> -<VarListEntry> -<Term>dbname[@server][:port][as <Replaceable>connection name</Replaceable>][user <Replaceable>user name</Replaceable>]</Term> -<listitem><para></para></listitem> -</VarListEntry> - -<VarListEntry> -<Term>tcp:postgresql://server[:port][/dbname][as <Replaceable>connection name</Replaceable>][user <Replaceable>user name</Replaceable>]</Term> -<listitem><para></para></listitem> -</VarListEntry> - -<VarListEntry> -<Term>unix:postgresql://server[:port][/dbname][as <Replaceable>connection name</Replaceable>][user <Replaceable>user name</Replaceable>]</Term> -<listitem><para></para></listitem> -</VarListEntry> - -<VarListEntry> -<Term><Replaceable>character variable</Replaceable>[as <Replaceable>connection name</Replaceable>][user <Replaceable>user name</Replaceable>]</Term> -<listitem><para></para></listitem> -</VarListEntry> - -<VarListEntry> -<Term><Replaceable>character string</Replaceable>[as <Replaceable>connection name</Replaceable>][<Replaceable>user</Replaceable>]</Term> -<listitem><para></para></listitem> -</VarListEntry> - -<VarListEntry> -<Term>default</Term> -<listitem><para></para></listitem> -</VarListEntry> - -<VarListEntry> -<Term>user</Term> -<listitem><para></para></listitem> -</VarListEntry> -</VariableList> -</Para> - -<Para> -There are also different ways to specify the user name: -<VariableList> -<VarListEntry> -<Term><Replaceable>userid</Replaceable></Term> -<listitem><para></para></listitem> -</VarListEntry> -<VarListEntry> -<Term><Replaceable>userid</Replaceable>/<Replaceable>password</Replaceable></Term> -<listitem><para></para></listitem> -</VarListEntry> -<VarListEntry> -<Term><Replaceable>userid</Replaceable> identified by <Replaceable>password</Replaceable></Term> -<listitem><para></para></listitem> -</VarListEntry> -<VarListEntry> -<Term><Replaceable>userid</Replaceable> using <Replaceable>password</Replaceable></Term> -<listitem><para></para></listitem> -</VarListEntry> -</VariableList> -</Para> - -<Para> Finally the userid and the password. Each may be a constant text, a -character variable or a chararcter string. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>Disconnect statements</Term> -<ListItem> -<Para> -A disconnect statement looks loke: -<ProgramListing> -exec sql disconnect [<Replaceable>connection target</Replaceable>]; -</ProgramListing> -It closes the connection to the specified database. -</Para> - -<Para> -The <Replaceable>connection target</Replaceable> can be specified in the -following ways: -<VariableList> -<VarListEntry> -<Term><Replaceable>connection name</Replaceable></Term> -<listitem><para></para></listitem> -</VarListEntry> -<VarListEntry> -<Term>default</Term> -<listitem><para></para></listitem> -</VarListEntry> -<VarListEntry> -<Term>current</Term> -<listitem><para></para></listitem> -</VarListEntry> -<VarListEntry> -<Term>all</Term> -<listitem><para></para></listitem> -</VarListEntry> -</VariableList> -</Para> -</ListItem> -</VarListEntry> - -<!--WARNING: FROM HERE ON THE TEXT IS OUTDATED!--> -<VarListEntry> -<Term>Open cursor statement</Term> -<ListItem> -<Para> -An open cursor statement looks like: -<ProgramListing> -exec sql open <Replaceable>cursor</Replaceable>; -</ProgramListing> -and is ignore and not copied from the output. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>Commit statement</Term> -<ListItem> -<Para> -A commit statement looks like -<ProgramListing> + </programlisting> + </para> + + <para> + Instead the file specified is parsed by <application>ecpg</application> + itself. So the contents of the specified file is included in the resulting C + code. This way you are able to specify EXEC SQL commands in an include file. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Connect statement</term> + <listitem> + <para> + A connect statement looks like: + <programlisting> +exec sql connect to <replaceable>connection target</replaceable>; + </programlisting> + It creates a connection to the specified database. + </para> + + <para> + The <replaceable>connection target</replaceable> can be specified in the + following ways: + <variablelist> + <varlistentry> + <term>dbname[@server][:port][as <replaceable>connection + name</replaceable>][user <replaceable>user name</replaceable>]</term> + <listitem><para></para></listitem> + </varlistentry> + + <varlistentry> + <term>tcp:postgresql://server[:port][/dbname][as + <replaceable>connection name</replaceable>][user <replaceable>user name</replaceable>]</term> + <listitem><para></para></listitem> + </varlistentry> + + <varlistentry> + <term>unix:postgresql://server[:port][/dbname][as + <replaceable>connection name</replaceable>][user <replaceable>user name</replaceable>]</term> + <listitem><para></para></listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>character variable</replaceable>[as + <replaceable>connection name</replaceable>][user <replaceable>user name</replaceable>]</term> + <listitem><para></para></listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>character string</replaceable>[as + <replaceable>connection name</replaceable>][<replaceable>user</replaceable>]</term> + <listitem><para></para></listitem> + </varlistentry> + + <varlistentry> + <term>default</term> + <listitem><para></para></listitem> + </varlistentry> + + <varlistentry> + <term>user</term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </para> + + <para> + There are also different ways to specify the user name: + <variablelist> + <varlistentry> + <term><replaceable>userid</replaceable></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>userid</replaceable>/<replaceable>password</replaceable></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>userid</replaceable> identified by <replaceable>password</replaceable></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>userid</replaceable> using <replaceable>password</replaceable></term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </para> + + <para> Finally the userid and the password. Each may be a constant text, a + character variable or a chararcter string. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Disconnect statements</term> + <listitem> + <para> + A disconnect statement looks loke: + <programlisting> +exec sql disconnect [<replaceable>connection target</replaceable>]; + </programlisting> + It closes the connection to the specified database. + </para> + + <para> + The <replaceable>connection target</replaceable> can be specified in the + following ways: + <variablelist> + <varlistentry> + <term><replaceable>connection name</replaceable></term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term>default</term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term>current</term> + <listitem><para></para></listitem> + </varlistentry> + <varlistentry> + <term>all</term> + <listitem><para></para></listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + + <!--WARNING: FROM HERE ON THE TEXT IS OUTDATED!--> + <varlistentry> + <term>Open cursor statement</term> + <listitem> + <para> + An open cursor statement looks like: + <programlisting> +exec sql open <replaceable>cursor</replaceable>; + </programlisting> + and is ignore and not copied from the output. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Commit statement</term> + <listitem> + <para> + A commit statement looks like + <programlisting> exec sql commit; -</ProgramListing> -and is translated on the output to -<ProgramListing> + </programlisting> + and is translated on the output to + <programlisting> ECPGcommit(__LINE__); -</ProgramListing> -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>Rollback statement</Term> -<ListItem> -<Para> -A rollback statement looks like -<ProgramListing> + </programlisting> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Rollback statement</term> + <listitem> + <para> + A rollback statement looks like + <programlisting> exec sql rollback; -</ProgramListing> -and is translated on the output to -<ProgramListing> + </programlisting> + and is translated on the output to + <programlisting> ECPGrollback(__LINE__); -</ProgramListing> -</Para> -</ListItem> -</VarListEntry> - -<!--STARTING HERE IT IS OKAY AGAIN!--> -<VarListEntry> -<Term>Other statements</Term> -<ListItem> -<Para> -Other <Acronym>SQL</Acronym> statements are other statements that start with -<Command>exec sql</Command> and ends with <Command>;</Command>. -Everything inbetween is treated -as an <Acronym>SQL</Acronym> statement and parsed for variable substitution. -</Para> - -<Para> -Variable substitution occur when a symbol starts with a colon -(<Command>:</Command>). Then a variable with that name is looked for among -the variables that were previously declared within a declare section and -depending on the variable being for input or output the pointers to the -variables are written to the output to allow for access by the function. -</Para> - -<Para> -For every variable that is part of the <Acronym>SQL</Acronym> request -the function gets another ten arguments: - -<SimpleList> -<Member>The type as a special symbol.</Member> -<Member>A pointer to the value or a pointer to the pointer.</Member> -<Member>The size of the variable if it is a char or varchar.</Member> -<Member>Number of elements in the array (for array fetches).</Member> -<Member>The offset to the next element in the array (for array fetches)</Member> -<Member>The type of the indicator variable as a special symbol.</Member> -<Member>A pointer to the value of the indicator variable or a pointer to the pointer of the indicator variable.</Member> -<Member>0.</Member> -<Member>Number of elements in the indicator array (for array fetches).</Member> -<Member>The offset to the next element in the indicator array (for array fetches)</Member> -</SimpleList> -</Para> - -</ListItem> -</VarListEntry> -</VariableList> -</Para> -</Sect2> - -<Sect2> -<Title>A Complete Example</Title> - -<Para> -Here is a complete example describing the output of the preprocessor of a -file foo.pgc: -<ProgramListing> + </programlisting> + </para> + </listitem> + </varlistentry> + + <!--STARTING HERE IT IS OKAY AGAIN!--> + <varlistentry> + <term>Other statements</term> + <listitem> + <para> + Other <acronym>SQL</acronym> statements are other statements that start with + <command>exec sql</command> and ends with <command>;</command>. + Everything inbetween is treated + as an <acronym>SQL</acronym> statement and parsed for variable substitution. + </para> + + <para> + Variable substitution occur when a symbol starts with a colon + (<command>:</command>). Then a variable with that name is looked for among + the variables that were previously declared within a declare section and + depending on the variable being for input or output the pointers to the + variables are written to the output to allow for access by the function. + </para> + + <para> + For every variable that is part of the <acronym>SQL</acronym> request + the function gets another ten arguments: + + <simplelist> + <member>The type as a special symbol.</member> + <member>A pointer to the value or a pointer to the pointer.</member> + <member>The size of the variable if it is a char or varchar.</member> + <member>Number of elements in the array (for array fetches).</member> + <member>The offset to the next element in the array (for array fetches)</member> + <member>The type of the indicator variable as a special symbol.</member> + <member>A pointer to the value of the indicator variable or a pointer to the pointer of the indicator variable.</member> + <member>0.</member> + <member>Number of elements in the indicator array (for array fetches).</member> + <member>The offset to the next element in the indicator array (for array fetches)</member> + </simplelist> + </para> + + </listitem> + </varlistentry> + </variablelist> + </para> + </sect2> + + <sect2> + <title>A Complete Example</title> + + <para> + Here is a complete example describing the output of the preprocessor of a + file foo.pgc: + <programlisting> exec sql begin declare section; int index; int result; exec sql end declare section; ... exec sql select res into :result from mytable where index = :index; -</ProgramListing> -is translated into: -<ProgramListing> + </programlisting> + is translated into: + <programlisting> /* Processed by ecpg (2.6.0) */ /* These two include files are added by the preprocessor */ #include <ecpgtype.h>; @@ -923,100 +935,117 @@ ECPGdo(__LINE__, NULL, "select res from mytable where index = ? ", ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EORT); #line 147 "foo.pgc" -</ProgramListing> -(the indentation in this manual is added for readability and not -something that the preprocessor can do.) -</Para> -</sect2> - -<Sect2> -<Title>The Library</Title> - -<Para> -The most important function in the library is the <Function>ECPGdo</Function> -function. It takes a variable amount of arguments. Hopefully we will not run -into machines with limits on the amount of variables that can be -accepted by a vararg function. This could easily add up to 50 or so -arguments. -</Para> - -<Para> -The arguments are: - -<VariableList> -<VarListEntry> -<Term>A line number</Term> -<ListItem> -<Para> -This is a line number for the original line used in error messages only. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>A string</Term> -<ListItem> -<Para> -This is the <Acronym>SQL</Acronym> request that is to be issued. -This request is modified -by the input variables, i.e. the variables that where not known at -compile time but are to be entered in the request. Where the variables -should go the string contains <Quote>;</Quote>. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>Input variables</Term> -<ListItem> -<Para> -As described in the section about the preprocessor every input variable -gets ten arguments. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>ECPGt_EOIT</Term> -<ListItem> -<Para> -An enum telling that there are no more input variables. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>Output variables</Term> -<ListItem> -<Para> -As described in the section about the preprocessor every input variable -gets ten arguments. These variables are filled by the function. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>ECPGt_EORT</Term> -<ListItem> -<Para> -An enum telling that there are no more variables. -</Para> -</ListItem> -</VarListEntry> -</VariableList> -</Para> - -<Para> -All the <Acronym>SQL</Acronym> statements are performed in one transaction -unless you issue a commit transaction. To get this auto-transaction going -the first statement or the first after statement after a commit or rollback -always begins a transaction. To disable this feature per default use the -'-t' option on the commandline -</Para> - -<Para> -To be completed: entries describing the other entries. -</Para> -</sect2> -</sect1> -</Chapter> + </programlisting> + (the indentation in this manual is added for readability and not + something that the preprocessor can do.) + </para> + </sect2> + + <sect2> + <title>The Library</title> + + <para> + The most important function in the library is the <function>ECPGdo</function> + function. It takes a variable amount of arguments. Hopefully we will not run + into machines with limits on the amount of variables that can be + accepted by a vararg function. This could easily add up to 50 or so + arguments. + </para> + + <para> + The arguments are: + + <variablelist> + <varlistentry> + <term>A line number</term> + <listitem> + <para> + This is a line number for the original line used in error messages only. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>A string</term> + <listitem> + <para> + This is the <acronym>SQL</acronym> request that is to be issued. + This request is modified + by the input variables, i.e. the variables that where not known at + compile time but are to be entered in the request. Where the variables + should go the string contains <quote>;</quote>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Input variables</term> + <listitem> + <para> + As described in the section about the preprocessor every input variable + gets ten arguments. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ECPGt_EOIT</term> + <listitem> + <para> + An enum telling that there are no more input variables. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Output variables</term> + <listitem> + <para> + As described in the section about the preprocessor every input variable + gets ten arguments. These variables are filled by the function. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ECPGt_EORT</term> + <listitem> + <para> + An enum telling that there are no more variables. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + All the <acronym>SQL</acronym> statements are performed in one transaction + unless you issue a commit transaction. To get this auto-transaction going + the first statement or the first after statement after a commit or rollback + always begins a transaction. To disable this feature per default use the + <option>-t</option> option on the commandline. + </para> + + <para> + To be completed: entries describing the other entries. + </para> + </sect2> + </sect1> + </chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode:sgml +sgml-omittag:nil +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"./reference.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:("/usr/lib/sgml/CATALOG") +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index efb7f15de05..ec84abeb92f 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -1404,7 +1404,7 @@ Not defined by this name. Implements the intersection operator '#' <!-- Keep this comment at the end of the file Local variables: -mode: sgml +mode:sgml sgml-omittag:nil sgml-shorttag:t sgml-minimize-attributes:nil @@ -1414,7 +1414,7 @@ sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"./reference.ced" sgml-exposed-tags:nil -sgml-local-catalogs:"/usr/lib/sgml/catalog" +sgml-local-catalogs:("/usr/lib/sgml/catalog") sgml-local-ecat-files:nil End: --> diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml index 32aa5e7892e..2ea3e90879d 100644 --- a/doc/src/sgml/indices.sgml +++ b/doc/src/sgml/indices.sgml @@ -394,7 +394,7 @@ CREATE MEMSTORE ON <table> COLUMNS <cols> <!-- Keep this comment at the end of the file Local variables: -mode: sgml +mode:sgml sgml-omittag:nil sgml-shorttag:t sgml-minimize-attributes:nil @@ -404,7 +404,7 @@ sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"./reference.ced" sgml-exposed-tags:nil -sgml-local-catalogs:"/usr/lib/sgml/catalog" +sgml-local-catalogs:("/usr/lib/sgml/catalog") sgml-local-ecat-files:nil End: --> diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index fb48215c85a..048cda62469 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -1,10 +1,17 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.7 1999/12/06 16:37:11 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.8 2000/03/30 22:22:40 thomas Exp $ Postgres quick Installation Guide. - thomas 1998-10-26 $Log: installation.sgml,v $ +Revision 1.8 2000/03/30 22:22:40 thomas +Accumulated fixups. +Add some chapters on new topics. +Change to referencing OASIS/Docbook v3.1 rather than Davenport/Docbook v3.0 +Grepped for and fixed apparent tag mangling from emacs + "Normalize" operation. Should be the last of those. + Revision 1.7 1999/12/06 16:37:11 thomas Remove references to PostgreSQL as "public-domain" since that has a specific meaning wrt copyright (or lack thereof). @@ -39,7 +46,7 @@ First cut at standalone installation guide to replace INSTALL text source. --> -<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [ +<!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ <!entity about SYSTEM "about.sgml"> <!entity history SYSTEM "history.sgml"> diff --git a/doc/src/sgml/intro-ag.sgml b/doc/src/sgml/intro-ag.sgml index 83d18555c34..f7ad4c78186 100644 --- a/doc/src/sgml/intro-ag.sgml +++ b/doc/src/sgml/intro-ag.sgml @@ -19,6 +19,7 @@ &info; ¬ation; + &problems; &y2k; &legal; @@ -26,7 +27,7 @@ <!-- Keep this comment at the end of the file Local variables: -mode: sgml +mode:sgml sgml-omittag:nil sgml-shorttag:t sgml-minimize-attributes:nil @@ -36,7 +37,7 @@ sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"./reference.ced" sgml-exposed-tags:nil -sgml-local-catalogs:"/usr/lib/sgml/CATALOG" +sgml-local-catalogs:("/usr/lib/sgml/CATALOG") sgml-local-ecat-files:nil End: --> diff --git a/doc/src/sgml/intro-pg.sgml b/doc/src/sgml/intro-pg.sgml index 093ab42c4be..a8cb214e4ec 100644 --- a/doc/src/sgml/intro-pg.sgml +++ b/doc/src/sgml/intro-pg.sgml @@ -39,6 +39,7 @@ &info; ¬ation; + &problems; &y2k; &legal; @@ -46,7 +47,7 @@ <!-- Keep this comment at the end of the file Local variables: -mode: sgml +mode:sgml sgml-omittag:nil sgml-shorttag:t sgml-minimize-attributes:nil @@ -56,7 +57,7 @@ sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"./reference.ced" sgml-exposed-tags:nil -sgml-local-catalogs:"/usr/lib/sgml/CATALOG" +sgml-local-catalogs:("/usr/lib/sgml/CATALOG") sgml-local-ecat-files:nil End: --> diff --git a/doc/src/sgml/intro.sgml b/doc/src/sgml/intro.sgml index d5eea403dcb..eba5ac85815 100644 --- a/doc/src/sgml/intro.sgml +++ b/doc/src/sgml/intro.sgml @@ -73,7 +73,7 @@ &about; &info; ¬ation; - &bug-reporting; + &problems; &y2k; &legal; diff --git a/doc/src/sgml/jdbc.sgml b/doc/src/sgml/jdbc.sgml index 45a11e0dc80..0e2fc75b594 100644 --- a/doc/src/sgml/jdbc.sgml +++ b/doc/src/sgml/jdbc.sgml @@ -233,13 +233,13 @@ Class.forName("postgresql.Driver"); <listitem> <para> - jdbc:postgresql://<replaceable class="parameter">>hos</replaceable>>/<replaceable class="parameter">database</replaceable> + jdbc:postgresql://<replaceable class="parameter">host</replaceable>/<replaceable class="parameter">database</replaceable> </para> </listitem> <listitem> <para> - jdbc:postgresql://<replaceable class="parameter">>hos</replaceable>><replaceable class="parameter">">po</replaceable>e>/<replaceable class="parameter">database</replaceable> + jdbc:postgresql://<replaceable class="parameter">host</replaceable><replaceable class="parameter">port</replaceable>/<replaceable class="parameter">database</replaceable> </para> </listitem> </itemizedlist> diff --git a/doc/src/sgml/libpgtcl.sgml b/doc/src/sgml/libpgtcl.sgml index 682f7ad1824..724bbff5973 100644 --- a/doc/src/sgml/libpgtcl.sgml +++ b/doc/src/sgml/libpgtcl.sgml @@ -671,6 +671,16 @@ the number of attributes in each tuple. </VARLISTENTRY> <VARLISTENTRY> <TERM> +-list VarName +</TERM> +<LISTITEM> +<PARA> +assign the results to a list of lists. +</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM> -assign arrayName </TERM> <LISTITEM> diff --git a/doc/src/sgml/plan.sgml b/doc/src/sgml/plan.sgml new file mode 100644 index 00000000000..ef30a1a2a7f --- /dev/null +++ b/doc/src/sgml/plan.sgml @@ -0,0 +1,263 @@ + <chapter> + <title>Understanding Performance</title> + + <para> + Query performance can be affected by many things. Some of these can + be manipulated by the user, while others are fundamental to the underlying + design of the system. + </para> + + <para> + Some performance issues, such as index creation and bulk data + loading, are covered elsewhere. This chapter will discuss the + <command>EXPLAIN</command> command, and will show how the details + of a query can affect the query plan, and hence overall + performance. + </para> + + <sect1> + <title>Using <command>EXPLAIN</command></title> + + <note> + <title>Author</title> + <para> + Written by Tom Lane, from e-mail dated 2000-03-27. + </para> + </note> + + <para> + Plan-reading is an art that deserves a tutorial, and I haven't + had time to write one. Here is some quick & dirty explanation. + </para> + + <para> + The numbers that are currently quoted by EXPLAIN are: + + <itemizedlist> + <listitem> + <para> + Estimated startup cost (time expended before output scan can start, + eg, time to do the sorting in a SORT node). + </para> + </listitem> + + <listitem> + <para> + Estimated total cost (if all tuples are retrieved, which they may not + be --- LIMIT will stop short of paying the total cost, for + example). + </para> + </listitem> + + <listitem> + <para> + Estimated number of rows output by this plan node. + </para> + </listitem> + + <listitem> + <para> + Estimated average width (in bytes) of rows output by this plan + node. + </para> + </listitem> + </itemizedlist> + </para> + + <para> + The costs are measured in units of disk page fetches. (There are some + fairly bogus fudge-factors for converting CPU effort estimates into + disk-fetch units; see the SET ref page if you want to play with these.) + It's important to note that the cost of an upper-level node includes + the cost of all its child nodes. It's also important to realize that + the cost only reflects things that the planner/optimizer cares about. + In particular, the cost does not consider the time spent transmitting + result tuples to the frontend --- which could be a pretty dominant + factor in the true elapsed time, but the planner ignores it because + it cannot change it by altering the plan. (Every correct plan will + output the same tuple set, we trust.) + </para> + + <para> + Rows output is a little tricky because it is *not* the number of rows + processed/scanned by the query --- it is usually less, reflecting the + estimated selectivity of any WHERE-clause constraints that are being + applied at this node. + </para> + + <para> + Average width is pretty bogus because the thing really doesn't have + any idea of the average length of variable-length columns. I'm thinking + about improving that in the future, but it may not be worth the trouble, + because the width isn't used for very much. + </para> + + <para> + Here are some examples (using the regress test database after a + vacuum analyze, and current sources): + + <programlisting> +regression=# explain select * from tenk1; +NOTICE: QUERY PLAN: + +Seq Scan on tenk1 (cost=0.00..333.00 rows=10000 width=148) + </programlisting> + </para> + + <para> + About as straightforward as it gets. If you do + + <programlisting> +select * from pg_class where relname = 'tenk1'; + </programlisting> + + you'll find out that tenk1 has 233 disk + pages and 10000 tuples. So the cost is estimated at 233 block + reads, defined as 1.0 apiece, plus 10000 * cpu_tuple_cost which is + currently 0.01 (try <command>show cpu_tuple_cost</command>). + </para> + + <para> + Now let's modify the query to add a qualification clause: + + <programlisting> +regression=# explain select * from tenk1 where unique1 < 1000; +NOTICE: QUERY PLAN: + +Seq Scan on tenk1 (cost=0.00..358.00 rows=1000 width=148) + </programlisting> + + Estimated output rows has gone down because of the WHERE clause. + (The uncannily accurate estimate is just because tenk1 is a particularly + simple case --- the unique1 column has 10000 distinct values ranging + from 0 to 9999, so the estimator's linear interpolation between min and + max column values is dead-on.) However, the scan will still have to + visit all 10000 rows, so the cost hasn't decreased; in fact it has gone + up a bit to reflect the extra CPU time spent checking the WHERE + condition. + </para> + + <para> + Modify the query to restrict the qualification even more: + + <programlisting> +regression=# explain select * from tenk1 where unique1 < 100; +NOTICE: QUERY PLAN: + +Index Scan using tenk1_unique1 on tenk1 (cost=0.00..89.35 rows=100 width=148) + </programlisting> + + and you will see that if we make the WHERE condition selective + enough, the planner will + eventually decide that an indexscan is cheaper than a sequential scan. + This plan will only have to visit 100 tuples because of the index, + so it wins despite the fact that each individual fetch is expensive. + </para> + + <para> + Add another condition to the qualification: + + <programlisting> +regression=# explain select * from tenk1 where unique1 < 100 and +regression-# stringu1 = 'xxx'; +NOTICE: QUERY PLAN: + +Index Scan using tenk1_unique1 on tenk1 (cost=0.00..89.60 rows=1 width=148) + </programlisting> + + The added clause "stringu1 = 'xxx'" reduces the output-rows estimate, + but not the cost because we still have to visit the same set of tuples. + </para> + + <para> + Let's try joining two tables, using the fields we have been discussing: + + <programlisting> +regression=# explain select * from tenk1 t1, tenk2 t2 where t1.unique1 < 100 +regression-# and t1.unique2 = t2.unique2; +NOTICE: QUERY PLAN: + +Nested Loop (cost=0.00..144.07 rows=100 width=296) + -> Index Scan using tenk1_unique1 on tenk1 t1 + (cost=0.00..89.35 rows=100 width=148) + -> Index Scan using tenk2_unique2 on tenk2 t2 + (cost=0.00..0.53 rows=1 width=148) + </programlisting> + </para> + + <para> + In this nested-loop join, the outer scan is the same indexscan we had + in the example before last, and the cost and row count are the same + because we are applying the "unique1 < 100" WHERE clause at this node. + The "t1.unique2 = t2.unique2" clause isn't relevant yet, so it doesn't + affect the row count. For the inner scan, we assume that the current + outer-scan tuple's unique2 value is plugged into the inner indexscan + to produce an indexqual like + "t2.unique2 = <replaceable>constant</replaceable>". So we get the + same inner-scan plan and costs that we'd get from, say, "explain select + * from tenk2 where unique2 = 42". The loop node's costs are then set + on the basis of the outer scan's cost, plus one repetition of the + inner scan for each outer tuple (100 * 0.53, here), plus a little CPU + time for join processing. + </para> + + <para> + In this example the loop's output row count is the same as the product + of the two scans' row counts, but that's not true in general, because + in general you can have WHERE clauses that mention both relations and + so can only be applied at the join point, not to either input scan. + For example, if we added "WHERE ... AND t1.hundred < t2.hundred", + that'd decrease the output row count of the join node, but not change + either input scan. + </para> + + <para> + We can look at variant plans by forcing the planner to disregard + whatever strategy it thought was the winner (a pretty crude tool, + but it's what we've got at the moment): + + <programlisting> +regression=# set enable_nestloop = 'off'; +SET VARIABLE +regression=# explain select * from tenk1 t1, tenk2 t2 where t1.unique1 < 100 +regression-# and t1.unique2 = t2.unique2; +NOTICE: QUERY PLAN: + +Hash Join (cost=89.60..574.10 rows=100 width=296) + -> Seq Scan on tenk2 t2 + (cost=0.00..333.00 rows=10000 width=148) + -> Hash (cost=89.35..89.35 rows=100 width=148) + -> Index Scan using tenk1_unique1 on tenk1 t1 + (cost=0.00..89.35 rows=100 width=148) + </programlisting> + + This plan proposes to extract the 100 interesting rows of tenk1 + using ye same olde indexscan, stash them into an in-memory hash table, + and then do a sequential scan of tenk2, probing into the hash table + for possible matches of "t1.unique2 = t2.unique2" at each tenk2 tuple. + The cost to read tenk1 and set up the hash table is entirely startup + cost for the hash join, since we won't get any tuples out until we can + start reading tenk2. The total time estimate for the join also + includes a pretty hefty charge for CPU time to probe the hash table + 10000 times. Note, however, that we are NOT charging 10000 times 89.35; + the hash table setup is only done once in this plan type. + </para> + </sect1> + </chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode:sgml +sgml-omittag:nil +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"./reference.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:("/usr/lib/sgml/CATALOG") +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index e94e561ee8e..f189b9b010e 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -1,98 +1,104 @@ <!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ -<!entity about SYSTEM "about.sgml"> -<!entity bug-reporting SYSTEM "bug-reporting.sgml"> -<!entity history SYSTEM "history.sgml"> -<!entity info SYSTEM "info.sgml"> -<!entity legal SYSTEM "legal.sgml"> -<!entity notation SYSTEM "notation.sgml"> -<!entity y2k SYSTEM "y2k.sgml"> +<!entity about SYSTEM "about.sgml"> +<!entity history SYSTEM "history.sgml"> +<!entity info SYSTEM "info.sgml"> +<!entity legal SYSTEM "legal.sgml"> +<!entity notation SYSTEM "notation.sgml"> +<!entity problems SYSTEM "problems.sgml"> +<!entity y2k SYSTEM "y2k.sgml"> <!-- tutorial --> -<!entity arch SYSTEM "arch.sgml"> -<!entity intro SYSTEM "intro.sgml"> -<!entity query SYSTEM "query.sgml"> -<!entity sql SYSTEM "sql.sgml"> -<!entity start SYSTEM "start.sgml"> +<!entity arch SYSTEM "arch.sgml"> +<!entity intro SYSTEM "intro.sgml"> +<!entity query SYSTEM "query.sgml"> +<!entity sql SYSTEM "sql.sgml"> +<!entity start SYSTEM "start.sgml"> <!-- user's guide --> -<!entity advanced SYSTEM "advanced.sgml"> -<!entity array SYSTEM "array.sgml"> -<!entity datatype SYSTEM "datatype.sgml"> -<!entity datetime SYSTEM "datetime.sgml"> -<!entity environ SYSTEM "environ.sgml"> -<!entity func SYSTEM "func.sgml"> -<!entity indices SYSTEM "indices.sgml"> -<!entity inherit SYSTEM "inherit.sgml"> -<!entity manage SYSTEM "manage.sgml"> -<!entity mvcc SYSTEM "mvcc.sgml"> -<!entity oper SYSTEM "oper.sgml"> -<!entity pgaccess SYSTEM "pgaccess.sgml"> -<!entity psql SYSTEM "psql.sgml"> -<!entity query-ug SYSTEM "query-ug.sgml"> -<!entity storage SYSTEM "storage.sgml"> -<!entity syntax SYSTEM "syntax.sgml"> -<!entity typeconv SYSTEM "typeconv.sgml"> +<!entity advanced SYSTEM "advanced.sgml"> +<!entity array SYSTEM "array.sgml"> +<!entity datatype SYSTEM "datatype.sgml"> +<!entity datetime SYSTEM "datetime.sgml"> +<!entity environ SYSTEM "environ.sgml"> +<!entity func SYSTEM "func.sgml"> +<!entity indices SYSTEM "indices.sgml"> +<!entity inherit SYSTEM "inherit.sgml"> +<!entity manage SYSTEM "manage.sgml"> +<!entity mvcc SYSTEM "mvcc.sgml"> +<!entity oper SYSTEM "oper.sgml"> +<!entity plan SYSTEM "plan.sgml"> +<!entity plperl SYSTEM "plperl.sgml"> +<!entity plsql SYSTEM "plsql.sgml"> +<!entity pltcl SYSTEM "pltcl.sgml"> +<!entity populate SYSTEM "populate.sgml"> +<!entity psql SYSTEM "psql.sgml"> +<!entity query-ug SYSTEM "query-ug.sgml"> +<!entity storage SYSTEM "storage.sgml"> +<!entity syntax SYSTEM "syntax.sgml"> +<!entity typeconv SYSTEM "typeconv.sgml"> <!-- reference pages --> -<!entity % allfiles SYSTEM "ref/allfiles.sgml"> +<!entity % allfiles SYSTEM "ref/allfiles.sgml"> %allfiles; <!-- administrator's guide --> -<!entity config SYSTEM "config.sgml"> -<!entity intro-ag SYSTEM "intro-ag.sgml"> -<!entity install SYSTEM "install.sgml"> -<!entity installw SYSTEM "install-win32.sgml"> -<!entity layout SYSTEM "layout.sgml"> -<!entity manage-ag SYSTEM "manage-ag.sgml"> -<!entity ports SYSTEM "ports.sgml"> -<!entity recovery SYSTEM "recovery.sgml"> -<!entity regress SYSTEM "regress.sgml"> -<!entity release SYSTEM "release.sgml"> -<!entity runtime SYSTEM "runtime.sgml"> -<!entity security SYSTEM "security.sgml"> -<!entity start-ag SYSTEM "start-ag.sgml"> -<!entity trouble SYSTEM "trouble.sgml"> +<!entity config SYSTEM "config.sgml"> +<!entity intro-ag SYSTEM "intro-ag.sgml"> +<!entity install SYSTEM "install.sgml"> +<!entity installw SYSTEM "install-win32.sgml"> +<!entity layout SYSTEM "layout.sgml"> +<!entity manage-ag SYSTEM "manage-ag.sgml"> +<!entity ports SYSTEM "ports.sgml"> +<!entity recovery SYSTEM "recovery.sgml"> +<!entity regress SYSTEM "regress.sgml"> +<!entity release SYSTEM "release.sgml"> +<!entity runtime SYSTEM "runtime.sgml"> +<!entity security SYSTEM "security.sgml"> +<!entity start-ag SYSTEM "start-ag.sgml"> +<!entity trouble SYSTEM "trouble.sgml"> <!-- programmer's guide --> -<!entity arch-pg SYSTEM "arch-pg.sgml"> -<!entity dfunc SYSTEM "dfunc.sgml"> -<!entity ecpg SYSTEM "ecpg.sgml"> -<!entity extend SYSTEM "extend.sgml"> -<!entity func-ref SYSTEM "func-ref.sgml"> -<!entity gist SYSTEM "gist.sgml"> -<!entity intro-pg SYSTEM "intro-pg.sgml"> -<!entity jdbc SYSTEM "jdbc.sgml"> -<!entity libpq SYSTEM "libpq.sgml"> -<!entity libpqpp SYSTEM "libpq++.sgml"> -<!entity libpgtcl SYSTEM "libpgtcl.sgml"> -<!entity lisp SYSTEM "lisp.sgml"> -<!entity lobj SYSTEM "lobj.sgml"> -<!entity odbc SYSTEM "odbc.sgml"> -<!entity rules SYSTEM "rules.sgml"> -<!entity spi SYSTEM "spi.sgml"> -<!entity trigger SYSTEM "trigger.sgml"> -<!entity xaggr SYSTEM "xaggr.sgml"> -<!entity xfunc SYSTEM "xfunc.sgml"> -<!entity xindex SYSTEM "xindex.sgml"> -<!entity xplang SYSTEM "xplang.sgml"> -<!entity xoper SYSTEM "xoper.sgml"> -<!entity xtypes SYSTEM "xtypes.sgml"> +<!entity arch-pg SYSTEM "arch-pg.sgml"> +<!entity dfunc SYSTEM "dfunc.sgml"> +<!entity ecpg SYSTEM "ecpg.sgml"> +<!entity extend SYSTEM "extend.sgml"> +<!entity func-ref SYSTEM "func-ref.sgml"> +<!entity gist SYSTEM "gist.sgml"> +<!entity intro-pg SYSTEM "intro-pg.sgml"> +<!entity indexcost SYSTEM "indexcost.sgml"> +<!entity jdbc SYSTEM "jdbc.sgml"> +<!entity libpq SYSTEM "libpq.sgml"> +<!entity libpqpp SYSTEM "libpq++.sgml"> +<!entity libpgtcl SYSTEM "libpgtcl.sgml"> +<!entity lisp SYSTEM "lisp.sgml"> +<!entity lobj SYSTEM "lobj.sgml"> +<!entity odbc SYSTEM "odbc.sgml"> +<!entity rules SYSTEM "rules.sgml"> +<!entity spi SYSTEM "spi.sgml"> +<!entity trigger SYSTEM "trigger.sgml"> +<!entity xaggr SYSTEM "xaggr.sgml"> +<!entity xfunc SYSTEM "xfunc.sgml"> +<!entity xindex SYSTEM "xindex.sgml"> +<!entity xplang SYSTEM "xplang.sgml"> +<!entity xoper SYSTEM "xoper.sgml"> +<!entity xtypes SYSTEM "xtypes.sgml"> <!-- developer's guide --> -<!entity arch-dev SYSTEM "arch-dev.sgml"> -<!entity biblio SYSTEM "biblio.sgml"> -<!entity bki SYSTEM "bki.sgml"> -<!entity compiler SYSTEM "compiler.sgml"> -<!entity contacts SYSTEM "contacts.sgml"> -<!entity cvs SYSTEM "cvs.sgml"> -<!entity docguide SYSTEM "docguide.sgml"> -<!entity geqo SYSTEM "geqo.sgml"> -<!entity options SYSTEM "pg_options.sgml"> -<!entity page SYSTEM "page.sgml"> -<!entity protocol SYSTEM "protocol.sgml"> -<!entity signals SYSTEM "signals.sgml"> -<!entity sources SYSTEM "sources.sgml"> +<!entity arch-dev SYSTEM "arch-dev.sgml"> +<!entity biblio SYSTEM "biblio.sgml"> +<!entity bki SYSTEM "bki.sgml"> +<!entity compiler SYSTEM "compiler.sgml"> +<!entity contacts SYSTEM "contacts.sgml"> +<!entity cvs SYSTEM "cvs.sgml"> +<!entity docguide SYSTEM "docguide.sgml"> +<!entity geqo SYSTEM "geqo.sgml"> +<!entity index SYSTEM "index.sgml"> +<!entity options SYSTEM "pg_options.sgml"> +<!entity page SYSTEM "page.sgml"> +<!entity protocol SYSTEM "protocol.sgml"> +<!entity signals SYSTEM "signals.sgml"> +<!entity sources SYSTEM "sources.sgml"> ]> <!-- entity manpages SYSTEM "man/manpages.sgml" subdoc --> <Book Id="postgres"> @@ -181,10 +187,15 @@ Your name here... &indices; &array; &inherit; + &plsql; + &pltcl; + &plperl; &mvcc; &environ; &manage; &storage; + &plan; + &populate; &commands; </Part> @@ -237,6 +248,7 @@ Your name here... &xaggr; &rules; &xindex; + &indexcost; &gist; &dfunc; &trigger; diff --git a/doc/src/sgml/programmer.sgml b/doc/src/sgml/programmer.sgml index c01041fa4bf..b559f94ece4 100644 --- a/doc/src/sgml/programmer.sgml +++ b/doc/src/sgml/programmer.sgml @@ -1,9 +1,16 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.22 2000/03/28 14:16:06 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.23 2000/03/30 22:22:41 thomas Exp $ Postgres Programmer's Guide. $Log: programmer.sgml,v $ +Revision 1.23 2000/03/30 22:22:41 thomas +Accumulated fixups. +Add some chapters on new topics. +Change to referencing OASIS/Docbook v3.1 rather than Davenport/Docbook v3.0 +Grepped for and fixed apparent tag mangling from emacs + "Normalize" operation. Should be the last of those. + Revision 1.22 2000/03/28 14:16:06 thomas Update SGML catalog references to DocBook 3.1 on FreeBSD. Matches postgresql.org/hub.org environment. @@ -49,46 +56,49 @@ Make new file current.sgml to hold release info for the current release. <!entity info SYSTEM "info.sgml"> <!entity legal SYSTEM "legal.sgml"> <!entity notation SYSTEM "notation.sgml"> +<!entity problems SYSTEM "problems.sgml"> <!entity y2k SYSTEM "y2k.sgml"> -<!entity arch-pg SYSTEM "arch-pg.sgml"> -<!entity dfunc SYSTEM "dfunc.sgml"> -<!entity ecpg SYSTEM "ecpg.sgml"> -<!entity extend SYSTEM "extend.sgml"> -<!entity func-ref SYSTEM "func-ref.sgml"> -<!entity gist SYSTEM "gist.sgml"> -<!entity intro-pg SYSTEM "intro-pg.sgml"> -<!entity jdbc SYSTEM "jdbc.sgml"> -<!entity libpq SYSTEM "libpq.sgml"> -<!entity libpqpp SYSTEM "libpq++.sgml"> -<!entity libpgtcl SYSTEM "libpgtcl.sgml"> -<!entity lisp SYSTEM "lisp.sgml"> -<!entity lobj SYSTEM "lobj.sgml"> -<!entity odbc SYSTEM "odbc.sgml"> -<!entity rules SYSTEM "rules.sgml"> -<!entity spi SYSTEM "spi.sgml"> -<!entity trigger SYSTEM "trigger.sgml"> -<!entity xaggr SYSTEM "xaggr.sgml"> -<!entity xfunc SYSTEM "xfunc.sgml"> -<!entity xindex SYSTEM "xindex.sgml"> -<!entity xplang SYSTEM "xplang.sgml"> -<!entity xoper SYSTEM "xoper.sgml"> -<!entity xtypes SYSTEM "xtypes.sgml"> +<!entity arch-pg SYSTEM "arch-pg.sgml"> +<!entity dfunc SYSTEM "dfunc.sgml"> +<!entity ecpg SYSTEM "ecpg.sgml"> +<!entity extend SYSTEM "extend.sgml"> +<!entity func-ref SYSTEM "func-ref.sgml"> +<!entity gist SYSTEM "gist.sgml"> +<!entity intro-pg SYSTEM "intro-pg.sgml"> +<!entity indexcost SYSTEM "indexcost.sgml"> +<!entity jdbc SYSTEM "jdbc.sgml"> +<!entity libpq SYSTEM "libpq.sgml"> +<!entity libpqpp SYSTEM "libpq++.sgml"> +<!entity libpgtcl SYSTEM "libpgtcl.sgml"> +<!entity lisp SYSTEM "lisp.sgml"> +<!entity lobj SYSTEM "lobj.sgml"> +<!entity odbc SYSTEM "odbc.sgml"> +<!entity plperl SYSTEM "plperl.sgml"> +<!entity rules SYSTEM "rules.sgml"> +<!entity spi SYSTEM "spi.sgml"> +<!entity trigger SYSTEM "trigger.sgml"> +<!entity xaggr SYSTEM "xaggr.sgml"> +<!entity xfunc SYSTEM "xfunc.sgml"> +<!entity xindex SYSTEM "xindex.sgml"> +<!entity xplang SYSTEM "xplang.sgml"> +<!entity xoper SYSTEM "xoper.sgml"> +<!entity xtypes SYSTEM "xtypes.sgml"> <!-- developer's guide --> -<!entity arch-dev SYSTEM "arch-dev.sgml"> -<!entity biblio SYSTEM "biblio.sgml"> -<!entity bki SYSTEM "bki.sgml"> -<!entity compiler SYSTEM "compiler.sgml"> -<!entity contacts SYSTEM "contacts.sgml"> -<!entity cvs SYSTEM "cvs.sgml"> -<!entity docguide SYSTEM "docguide.sgml"> -<!entity geqo SYSTEM "geqo.sgml"> -<!entity options SYSTEM "pg_options.sgml"> -<!entity page SYSTEM "page.sgml"> -<!entity protocol SYSTEM "protocol.sgml"> -<!entity signals SYSTEM "signals.sgml"> -<!entity sources SYSTEM "sources.sgml"> +<!entity arch-dev SYSTEM "arch-dev.sgml"> +<!entity biblio SYSTEM "biblio.sgml"> +<!entity bki SYSTEM "bki.sgml"> +<!entity compiler SYSTEM "compiler.sgml"> +<!entity contacts SYSTEM "contacts.sgml"> +<!entity cvs SYSTEM "cvs.sgml"> +<!entity docguide SYSTEM "docguide.sgml"> +<!entity geqo SYSTEM "geqo.sgml"> +<!entity options SYSTEM "pg_options.sgml"> +<!entity page SYSTEM "page.sgml"> +<!entity protocol SYSTEM "protocol.sgml"> +<!entity signals SYSTEM "signals.sgml"> +<!entity sources SYSTEM "sources.sgml"> ]> <book id="programmer"> @@ -169,8 +179,10 @@ Your name here... &xaggr; &rules; &xindex; + &indexcost; &gist; &xplang; + &plperl; &dfunc; <!-- reference --> diff --git a/doc/src/sgml/refentry.sgml b/doc/src/sgml/refentry.sgml index 720d8bd1b7f..64d102c1308 100644 --- a/doc/src/sgml/refentry.sgml +++ b/doc/src/sgml/refentry.sgml @@ -1 +1 @@ -<!doctype refentry PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> +<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml index 5dcda9acacd..7dd2eeaafb1 100644 --- a/doc/src/sgml/reference.sgml +++ b/doc/src/sgml/reference.sgml @@ -1,10 +1,17 @@ <!-- reference.sgml -$Header: /cvsroot/pgsql/doc/src/sgml/reference.sgml,v 1.6 1999/05/26 17:30:30 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/reference.sgml,v 1.7 2000/03/30 22:22:41 thomas Exp $ Postgres User's Reference documentation. - thomas 1998-08-31 $Log: reference.sgml,v $ +Revision 1.7 2000/03/30 22:22:41 thomas +Accumulated fixups. +Add some chapters on new topics. +Change to referencing OASIS/Docbook v3.1 rather than Davenport/Docbook v3.0 +Grepped for and fixed apparent tag mangling from emacs + "Normalize" operation. Should be the last of those. + Revision 1.6 1999/05/26 17:30:30 thomas Add chapters on CVS access, MVCC, SQL theory to the docs. Add an appendix with more details on date/time attributes and handling. @@ -24,7 +31,7 @@ Bigger updates to the installation instructions (install and config). --> -<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [ +<!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ <!entity intro SYSTEM "intro.sgml"> <!entity % allfiles SYSTEM "ref/allfiles.sgml"> diff --git a/doc/src/sgml/tutorial.sgml b/doc/src/sgml/tutorial.sgml index 0f1d93e45e3..02a210ac0ef 100644 --- a/doc/src/sgml/tutorial.sgml +++ b/doc/src/sgml/tutorial.sgml @@ -11,6 +11,7 @@ <!entity info SYSTEM "info.sgml"> <!entity legal SYSTEM "legal.sgml"> <!entity notation SYSTEM "notation.sgml"> +<!entity problems SYSTEM "problems.sgml"> <!entity y2k SYSTEM "y2k.sgml"> <!entity advanced SYSTEM "advanced.sgml"> diff --git a/doc/src/sgml/user.sgml b/doc/src/sgml/user.sgml index 3309737fd73..d770f9cc61f 100644 --- a/doc/src/sgml/user.sgml +++ b/doc/src/sgml/user.sgml @@ -1,29 +1,34 @@ <!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ -<!entity about SYSTEM "about.sgml"> -<!entity bug-reporting SYSTEM "bug-reporting.sgml"> -<!entity history SYSTEM "history.sgml"> -<!entity info SYSTEM "info.sgml"> -<!entity legal SYSTEM "legal.sgml"> -<!entity notation SYSTEM "notation.sgml"> -<!entity y2k SYSTEM "y2k.sgml"> - -<!entity advanced SYSTEM "advanced.sgml"> -<!entity array SYSTEM "array.sgml"> -<!entity biblio SYSTEM "biblio.sgml"> -<!entity datatype SYSTEM "datatype.sgml"> -<!entity datetime SYSTEM "datetime.sgml"> -<!entity environ SYSTEM "environ.sgml"> -<!entity func SYSTEM "func.sgml"> -<!entity indices SYSTEM "indices.sgml"> -<!entity inherit SYSTEM "inherit.sgml"> -<!entity intro SYSTEM "intro.sgml"> -<!entity manage SYSTEM "manage.sgml"> -<!entity mvcc SYSTEM "mvcc.sgml"> -<!entity oper SYSTEM "oper.sgml"> -<!entity storage SYSTEM "storage.sgml"> -<!entity syntax SYSTEM "syntax.sgml"> -<!entity typeconv SYSTEM "typeconv.sgml"> +<!entity about SYSTEM "about.sgml"> +<!entity history SYSTEM "history.sgml"> +<!entity info SYSTEM "info.sgml"> +<!entity legal SYSTEM "legal.sgml"> +<!entity notation SYSTEM "notation.sgml"> +<!entity problems SYSTEM "problems.sgml"> +<!entity y2k SYSTEM "y2k.sgml"> + +<!entity advanced SYSTEM "advanced.sgml"> +<!entity array SYSTEM "array.sgml"> +<!entity biblio SYSTEM "biblio.sgml"> +<!entity datatype SYSTEM "datatype.sgml"> +<!entity datetime SYSTEM "datetime.sgml"> +<!entity environ SYSTEM "environ.sgml"> +<!entity func SYSTEM "func.sgml"> +<!entity indices SYSTEM "indices.sgml"> +<!entity inherit SYSTEM "inherit.sgml"> +<!entity intro SYSTEM "intro.sgml"> +<!entity manage SYSTEM "manage.sgml"> +<!entity mvcc SYSTEM "mvcc.sgml"> +<!entity oper SYSTEM "oper.sgml"> +<!entity plan SYSTEM "plan.sgml"> +<!entity plperl SYSTEM "plperl.sgml"> +<!entity plsql SYSTEM "plsql.sgml"> +<!entity pltcl SYSTEM "pltcl.sgml"> +<!entity populate SYSTEM "populate.sgml"> +<!entity storage SYSTEM "storage.sgml"> +<!entity syntax SYSTEM "syntax.sgml"> +<!entity typeconv SYSTEM "typeconv.sgml"> <!-- reference pages --> <!entity % allfiles SYSTEM "allfiles.sgml"> @@ -108,10 +113,15 @@ Your name here... &indices; &array; &inherit; + &plsql; + &pltcl; + &plperl; &mvcc; &environ; &manage; &storage; + &plan; + &populate &commands; <!-- appendices --> |