+++ /dev/null
-<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>
- 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
- 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
- </para>
-
- <para>
- If your bug is a portability problem on a non-supported platform, send
- 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
- </para>
- </note>
- </Sect2>
-</Sect1>
-<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>.
-
-
-<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];
/* 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
-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>;
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:
+-->
--- /dev/null
+ <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:
+-->
<!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">
&indices;
&array;
&inherit;
+ &plsql;
+ &pltcl;
+ &plperl;
&mvcc;
&environ;
&manage;
&storage;
+ &plan;
+ &populate;
&commands;
</Part>
&xaggr;
&rules;
&xindex;
+ &indexcost;
&gist;
&dfunc;
&trigger;
projects / users / rhaas / postgres.git / commitdiff