-<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.80 2007/02/01 19:10:24 momjian Exp $ -->
+`<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.81 2007/02/16 03:50:29 momjian Exp $ -->
<chapter id="ecpg">
<title><application>ECPG</application> - Embedded <acronym>SQL</acronym> in C</title>
<synopsis>
date PGTYPESdate_from_timestamp(timestamp dt);
</synopsis>
- The function receives a timestamp as its only argument and returns the
- extracted date part from this timestamp.
+ The function receives a timestamp as its only argument and returns the
+ extracted date part from this timestamp.
</para>
</listitem>
</varlistentry>
<synopsis>
date PGTYPESdate_from_asc(char *str, char **endptr);
</synopsis>
- The function receives a C char* string <literal>str</> and a pointer to
- a C char* string <literal>endptr</>. At the moment ecpg always parses
- the complete string and so it currently does not support to store the
- address of the first invalid character in <literal>*endptr</literal>.
- You can safely set <literal>endptr</literal> to NULL.
+ The function receives a C char* string <literal>str</> and a pointer to
+ a C char* string <literal>endptr</>. At the moment ecpg always parses
+ the complete string and so it currently does not support to store the
+ address of the first invalid character in <literal>*endptr</literal>.
+ You can safely set <literal>endptr</literal> to NULL.
</para>
<para>
- Note that the function always assumes MDY-formatted dates and there is
- currently no variable to change that within ecpg.
+ Note that the function always assumes MDY-formatted dates and there is
+ currently no variable to change that within ecpg.
</para>
<para>
The following input formats are allowed:
<table>
- <title>Valid input formats for <function>PGTYPESdate_from_asc</function></title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Input</entry>
- <entry>Result</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>January 8, 1999</literal></entry>
- <entry><literal>January 8, 1999</literal></entry>
- </row>
- <row>
- <entry><literal>1999-01-08</literal></entry>
- <entry><literal>January 8, 1999</literal></entry>
- </row>
- <row>
- <entry><literal>1/8/1999</literal></entry>
- <entry><literal>January 8, 1999</literal></entry>
- </row>
- <row>
- <entry><literal>1/18/1999</literal></entry>
- <entry><literal>January 18, 1999</literal></entry>
- </row>
- <row>
- <entry><literal>01/02/03</literal></entry>
- <entry><literal>February 1, 2003</literal></entry>
- </row>
- <row>
- <entry><literal>1999-Jan-08</literal></entry>
- <entry><literal>January 8, 1999</literal></entry>
- </row>
- <row>
- <entry><literal>Jan-08-1999</literal></entry>
- <entry><literal>January 8, 1999</literal></entry>
- </row>
- <row>
- <entry><literal>08-Jan-1999</literal></entry>
- <entry><literal>January 8, 1999</literal></entry>
- </row>
- <row>
- <entry><literal>99-Jan-08</literal></entry>
- <entry><literal>January 8, 1999</literal></entry>
- </row>
- <row>
- <entry><literal>08-Jan-99</literal></entry>
- <entry><literal>January 8, 1999</literal></entry>
- </row>
- <row>
- <entry><literal>08-Jan-06</literal></entry>
- <entry><literal>January 8, 2006</literal></entry>
- </row>
- <row>
- <entry><literal>Jan-08-99</literal></entry>
- <entry><literal>January 8, 1999</literal></entry>
- </row>
- <row>
- <entry><literal>19990108</literal></entry>
- <entry><literal>ISO 8601; January 8, 1999</literal></entry>
- </row>
- <row>
- <entry><literal>990108</literal></entry>
- <entry><literal>ISO 8601; January 8, 1999</literal></entry>
- </row>
- <row>
- <entry><literal>1999.008</literal></entry>
- <entry><literal>year and day of year</literal></entry>
- </row>
- <row>
- <entry><literal>J2451187</literal></entry>
- <entry><literal>Julian day</literal></entry>
- </row>
- <row>
- <entry><literal>January 8, 99 BC</literal></entry>
- <entry><literal>year 99 before the Common Era</literal></entry>
- </row>
+ <title>Valid input formats for <function>PGTYPESdate_from_asc</function></title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Input</entry>
+ <entry>Result</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>January 8, 1999</literal></entry>
+ <entry><literal>January 8, 1999</literal></entry>
+ </row>
+ <row>
+ <entry><literal>1999-01-08</literal></entry>
+ <entry><literal>January 8, 1999</literal></entry>
+ </row>
+ <row>
+ <entry><literal>1/8/1999</literal></entry>
+ <entry><literal>January 8, 1999</literal></entry>
+ </row>
+ <row>
+ <entry><literal>1/18/1999</literal></entry>
+ <entry><literal>January 18, 1999</literal></entry>
+ </row>
+ <row>
+ <entry><literal>01/02/03</literal></entry>
+ <entry><literal>February 1, 2003</literal></entry>
+ </row>
+ <row>
+ <entry><literal>1999-Jan-08</literal></entry>
+ <entry><literal>January 8, 1999</literal></entry>
+ </row>
+ <row>
+ <entry><literal>Jan-08-1999</literal></entry>
+ <entry><literal>January 8, 1999</literal></entry>
+ </row>
+ <row>
+ <entry><literal>08-Jan-1999</literal></entry>
+ <entry><literal>January 8, 1999</literal></entry>
+ </row>
+ <row>
+ <entry><literal>99-Jan-08</literal></entry>
+ <entry><literal>January 8, 1999</literal></entry>
+ </row>
+ <row>
+ <entry><literal>08-Jan-99</literal></entry>
+ <entry><literal>January 8, 1999</literal></entry>
+ </row>
+ <row>
+ <entry><literal>08-Jan-06</literal></entry>
+ <entry><literal>January 8, 2006</literal></entry>
+ </row>
+ <row>
+ <entry><literal>Jan-08-99</literal></entry>
+ <entry><literal>January 8, 1999</literal></entry>
+ </row>
+ <row>
+ <entry><literal>19990108</literal></entry>
+ <entry><literal>ISO 8601; January 8, 1999</literal></entry>
+ </row>
+ <row>
+ <entry><literal>990108</literal></entry>
+ <entry><literal>ISO 8601; January 8, 1999</literal></entry>
+ </row>
+ <row>
+ <entry><literal>1999.008</literal></entry>
+ <entry><literal>year and day of year</literal></entry>
+ </row>
+ <row>
+ <entry><literal>J2451187</literal></entry>
+ <entry><literal>Julian day</literal></entry>
+ </row>
+ <row>
+ <entry><literal>January 8, 99 BC</literal></entry>
+ <entry><literal>year 99 before the Common Era</literal></entry>
+ </row>
</tbody>
</tgroup>
</table>
<synopsis>
char *PGTYPESdate_to_asc(date dDate);
</synopsis>
- The function receives the date <literal>dDate</> as its only parameter.
- It will output the date in the form <literal>1999-01-18</>, i.e. in the
- <literal>YYYY-MM-DD</> format.
+ The function receives the date <literal>dDate</> as its only parameter.
+ It will output the date in the form <literal>1999-01-18</>, i.e. in the
+ <literal>YYYY-MM-DD</> format.
</para>
</listitem>
</varlistentry>
<term><function>PGTYPESdate_julmdy</function></term>
<listitem>
<para>
- Extract the values for the day, the month and the year from a variable
- of type date.
+ Extract the values for the day, the month and the year from a variable
+ of type date.
<synopsis>
void PGTYPESdate_julmdy(date d, int *mdy);
</synopsis>
<!-- almost same description as for rjulmdy() -->
- The function receives the date <literal>d</> and a pointer to an array
- of 3 integer values <literal>mdy</>. The variable name indicates
- the sequential order: <literal>mdy[0]</> will be set to contain the
- number of the month, <literal>mdy[1]</> will be set to the value of the
- day and <literal>mdy[2]</> will contain the year.
+ The function receives the date <literal>d</> and a pointer to an array
+ of 3 integer values <literal>mdy</>. The variable name indicates
+ the sequential order: <literal>mdy[0]</> will be set to contain the
+ number of the month, <literal>mdy[1]</> will be set to the value of the
+ day and <literal>mdy[2]</> will contain the year.
</para>
</listitem>
</varlistentry>
<term><function>PGTYPESdate_mdyjul</function></term>
<listitem>
<para>
- Create a date value from an array of 3 integers that specify the
- day, the month and the year of the date.
+ Create a date value from an array of 3 integers that specify the
+ day, the month and the year of the date.
<synopsis>
void PGTYPESdate_mdyjul(int *mdy, date *jdate);
</synopsis>
- The function receives the array of the 3 integers (<literal>mdy</>) as
- its first argument and as its second argument a pointer to a variable
- of type date that should hold the result of the operation.
+ The function receives the array of the 3 integers (<literal>mdy</>) as
+ its first argument and as its second argument a pointer to a variable
+ of type date that should hold the result of the operation.
</para>
</listitem>
</varlistentry>
<synopsis>
int PGTYPESdate_dayofweek(date d);
</synopsis>
- The function receives the date variable <literal>d</> as its only
- argument and returns an integer that indicates the day of the week for
- this date.
+ The function receives the date variable <literal>d</> as its only
+ argument and returns an integer that indicates the day of the week for
+ this date.
<itemizedlist>
<listitem>
<para>
- 0 - Sunday
+ 0 - Sunday
</para>
</listitem>
<listitem>
<para>
- 1 - Monday
+ 1 - Monday
</para>
</listitem>
<listitem>
<para>
- 2 - Tuesday
+ 2 - Tuesday
</para>
</listitem>
<listitem>
<para>
- 3 - Wednesday
+ 3 - Wednesday
</para>
</listitem>
<listitem>
<para>
- 4 - Thursday
+ 4 - Thursday
</para>
</listitem>
<listitem>
<para>
- 5 - Friday
+ 5 - Friday
</para>
</listitem>
<listitem>
<para>
- 6 - Saturday
+ 6 - Saturday
</para>
</listitem>
</itemizedlist>
<synopsis>
void PGTYPESdate_today(date *d);
</synopsis>
- The function receives a pointer to a date variable (<literal>d</>)
- that it sets to the current date.
+ The function receives a pointer to a date variable (<literal>d</>)
+ that it sets to the current date.
</para>
</listitem>
</varlistentry>
<term><function>PGTYPESdate_fmt_asc</function></term>
<listitem>
<para>
- Convert a variable of type date to its textual representation using a
- format mask.
+ Convert a variable of type date to its textual representation using a
+ format mask.
<synopsis>
int PGTYPESdate_fmt_asc(date dDate, char *fmtstring, char *outbuf);
</synopsis>
- The function receives the date to convert (<literal>dDate</>), the
- format mask (<literal>fmtstring</>) and the string that will hold the
- textual representation of the date (<literal>outbuf</>).
+ The function receives the date to convert (<literal>dDate</>), the
+ format mask (<literal>fmtstring</>) and the string that will hold the
+ textual representation of the date (<literal>outbuf</>).
</para>
<para>
On success, 0 is returned and a negative value if an error occurred.
</para>
</listitem>
</itemizedlist>
- All other characters are copied 1:1 to the output string.
+ All other characters are copied 1:1 to the output string.
</para>
<para>
- The following table indicates a few possible formats. This will give
- you an idea of how to use this function. All output lines are based on
- the same date: November, 23rd, 1959.
+ The following table indicates a few possible formats. This will give
+ you an idea of how to use this function. All output lines are based on
+ the same date: November, 23rd, 1959.
<table>
- <title>Valid input formats for <function>PGTYPESdate_fmt_asc</function></title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>fmt</entry>
- <entry>result</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>mmddyy</literal></entry>
- <entry><literal>112359</literal></entry>
- </row>
- <row>
- <entry><literal>ddmmyy</literal></entry>
- <entry><literal>231159</literal></entry>
- </row>
- <row>
- <entry><literal>yymmdd</literal></entry>
- <entry><literal>591123</literal></entry>
- </row>
- <row>
- <entry><literal>yy/mm/dd</literal></entry>
- <entry><literal>59/11/23</literal></entry>
- </row>
- <row>
- <entry><literal>yy mm dd</literal></entry>
- <entry><literal>59 11 23</literal></entry>
- </row>
- <row>
- <entry><literal>yy.mm.dd</literal></entry>
- <entry><literal>59.11.23</literal></entry>
- </row>
- <row>
- <entry><literal>.mm.yyyy.dd.</literal></entry>
- <entry><literal>.11.1959.23.</literal></entry>
- </row>
- <row>
- <entry><literal>mmm. dd, yyyy</literal></entry>
- <entry><literal>Nov. 23, 1959</literal></entry>
- </row>
- <row>
- <entry><literal>mmm dd yyyy</literal></entry>
- <entry><literal>Nov 23 1959</literal></entry>
- </row>
- <row>
- <entry><literal>yyyy dd mm</literal></entry>
- <entry><literal>1959 23 11</literal></entry>
- </row>
- <row>
- <entry><literal>ddd, mmm. dd, yyyy</literal></entry>
- <entry><literal>Mon, Nov. 23, 1959</literal></entry>
- </row>
- <row>
- <entry><literal>(ddd) mmm. dd, yyyy</literal></entry>
- <entry><literal>(Mon) Nov. 23, 1959</literal></entry>
- </row>
+ <title>Valid input formats for <function>PGTYPESdate_fmt_asc</function></title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>fmt</entry>
+ <entry>result</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>mmddyy</literal></entry>
+ <entry><literal>112359</literal></entry>
+ </row>
+ <row>
+ <entry><literal>ddmmyy</literal></entry>
+ <entry><literal>231159</literal></entry>
+ </row>
+ <row>
+ <entry><literal>yymmdd</literal></entry>
+ <entry><literal>591123</literal></entry>
+ </row>
+ <row>
+ <entry><literal>yy/mm/dd</literal></entry>
+ <entry><literal>59/11/23</literal></entry>
+ </row>
+ <row>
+ <entry><literal>yy mm dd</literal></entry>
+ <entry><literal>59 11 23</literal></entry>
+ </row>
+ <row>
+ <entry><literal>yy.mm.dd</literal></entry>
+ <entry><literal>59.11.23</literal></entry>
+ </row>
+ <row>
+ <entry><literal>.mm.yyyy.dd.</literal></entry>
+ <entry><literal>.11.1959.23.</literal></entry>
+ </row>
+ <row>
+ <entry><literal>mmm. dd, yyyy</literal></entry>
+ <entry><literal>Nov. 23, 1959</literal></entry>
+ </row>
+ <row>
+ <entry><literal>mmm dd yyyy</literal></entry>
+ <entry><literal>Nov 23 1959</literal></entry>
+ </row>
+ <row>
+ <entry><literal>yyyy dd mm</literal></entry>
+ <entry><literal>1959 23 11</literal></entry>
+ </row>
+ <row>
+ <entry><literal>ddd, mmm. dd, yyyy</literal></entry>
+ <entry><literal>Mon, Nov. 23, 1959</literal></entry>
+ </row>
+ <row>
+ <entry><literal>(ddd) mmm. dd, yyyy</literal></entry>
+ <entry><literal>(Mon) Nov. 23, 1959</literal></entry>
+ </row>
</tbody>
</tgroup>
</table>
<term><function>PGTYPESdate_defmt_asc</function></term>
<listitem>
<para>
- Use a format mask to convert a C char* string to a value of type
- date.
+ Use a format mask to convert a C char* string to a value of type
+ date.
<synopsis>
int PGTYPESdate_defmt_asc(date *d, char *fmt, char *str);
</synopsis>
- <!-- same description as rdefmtdate -->
- The function receives a pointer to the date value that should hold the
- result of the operation (<literal>d</>), the format mask to use for
- parsing the date (<literal>fmt</>) and the C char* string containing
- the textual representation of the date (<literal>str</>). The textual
- representation is expected to match the format mask. However you do not
- need to have a 1:1 mapping of the string to the format mask. The
- function only analyzes the sequential order and looks for the literals
- <literal>yy</literal> or <literal>yyyy</literal> that indicate the
- position of the year, <literal>mm</literal> to indicate the position of
- the month and <literal>dd</literal> to indicate the position of the
- day.
- </para>
- <para>
- The following table indicates a few possible formats. This will give
- you an idea of how to use this function.
+ <!-- same description as rdefmtdate -->
+ The function receives a pointer to the date value that should hold the
+ result of the operation (<literal>d</>), the format mask to use for
+ parsing the date (<literal>fmt</>) and the C char* string containing
+ the textual representation of the date (<literal>str</>). The textual
+ representation is expected to match the format mask. However you do not
+ need to have a 1:1 mapping of the string to the format mask. The
+ function only analyzes the sequential order and looks for the literals
+ <literal>yy</literal> or <literal>yyyy</literal> that indicate the
+ position of the year, <literal>mm</literal> to indicate the position of
+ the month and <literal>dd</literal> to indicate the position of the
+ day.
+ </para>
+ <para>
+ The following table indicates a few possible formats. This will give
+ you an idea of how to use this function.
<table>
- <title>Valid input formats for <function>rdefmtdate</function></title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>fmt</entry>
- <entry>str</entry>
- <entry>result</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>ddmmyy</literal></entry>
- <entry><literal>21-2-54</literal></entry>
- <entry><literal>1954-02-21</literal></entry>
- </row>
- <row>
- <entry><literal>ddmmyy</literal></entry>
- <entry><literal>2-12-54</literal></entry>
- <entry><literal>1954-12-02</literal></entry>
- </row>
- <row>
- <entry><literal>ddmmyy</literal></entry>
- <entry><literal>20111954</literal></entry>
- <entry><literal>1954-11-20</literal></entry>
- </row>
- <row>
- <entry><literal>ddmmyy</literal></entry>
- <entry><literal>130464</literal></entry>
- <entry><literal>1964-04-13</literal></entry>
- </row>
- <row>
- <entry><literal>mmm.dd.yyyy</literal></entry>
- <entry><literal>MAR-12-1967</literal></entry>
- <entry><literal>1967-03-12</literal></entry>
- </row>
- <row>
- <entry><literal>yy/mm/dd</literal></entry>
- <entry><literal>1954, February 3rd</literal></entry>
- <entry><literal>1954-02-03</literal></entry>
- </row>
- <row>
- <entry><literal>mmm.dd.yyyy</literal></entry>
- <entry><literal>041269</literal></entry>
- <entry><literal>1969-04-12</literal></entry>
- </row>
- <row>
- <entry><literal>yy/mm/dd</literal></entry>
- <entry><literal>In the year 2525, in the month of July, mankind will be alive on the 28th day</literal></entry>
- <entry><literal>2525-07-28</literal></entry>
- </row>
- <row>
- <entry><literal>dd-mm-yy</literal></entry>
- <entry><literal>I said on the 28th of July in the year 2525</literal></entry>
- <entry><literal>2525-07-28</literal></entry>
- </row>
- <row>
- <entry><literal>mmm.dd.yyyy</literal></entry>
- <entry><literal>9/14/58</literal></entry>
- <entry><literal>1958-09-14</literal></entry>
- </row>
- <row>
- <entry><literal>yy/mm/dd</literal></entry>
- <entry><literal>47/03/29</literal></entry>
- <entry><literal>1947-03-29</literal></entry>
- </row>
- <row>
- <entry><literal>mmm.dd.yyyy</literal></entry>
- <entry><literal>oct 28 1975</literal></entry>
- <entry><literal>1975-10-28</literal></entry>
- </row>
- <row>
- <entry><literal>mmddyy</literal></entry>
- <entry><literal>Nov 14th, 1985</literal></entry>
- <entry><literal>1985-11-14</literal></entry>
- </row>
+ <title>Valid input formats for <function>rdefmtdate</function></title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>fmt</entry>
+ <entry>str</entry>
+ <entry>result</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>ddmmyy</literal></entry>
+ <entry><literal>21-2-54</literal></entry>
+ <entry><literal>1954-02-21</literal></entry>
+ </row>
+ <row>
+ <entry><literal>ddmmyy</literal></entry>
+ <entry><literal>2-12-54</literal></entry>
+ <entry><literal>1954-12-02</literal></entry>
+ </row>
+ <row>
+ <entry><literal>ddmmyy</literal></entry>
+ <entry><literal>20111954</literal></entry>
+ <entry><literal>1954-11-20</literal></entry>
+ </row>
+ <row>
+ <entry><literal>ddmmyy</literal></entry>
+ <entry><literal>130464</literal></entry>
+ <entry><literal>1964-04-13</literal></entry>
+ </row>
+ <row>
+ <entry><literal>mmm.dd.yyyy</literal></entry>
+ <entry><literal>MAR-12-1967</literal></entry>
+ <entry><literal>1967-03-12</literal></entry>
+ </row>
+ <row>
+ <entry><literal>yy/mm/dd</literal></entry>
+ <entry><literal>1954, February 3rd</literal></entry>
+ <entry><literal>1954-02-03</literal></entry>
+ </row>
+ <row>
+ <entry><literal>mmm.dd.yyyy</literal></entry>
+ <entry><literal>041269</literal></entry>
+ <entry><literal>1969-04-12</literal></entry>
+ </row>
+ <row>
+ <entry><literal>yy/mm/dd</literal></entry>
+ <entry><literal>In the year 2525, in the month of July, mankind will be alive on the 28th day</literal></entry>
+ <entry><literal>2525-07-28</literal></entry>
+ </row>
+ <row>
+ <entry><literal>dd-mm-yy</literal></entry>
+ <entry><literal>I said on the 28th of July in the year 2525</literal></entry>
+ <entry><literal>2525-07-28</literal></entry>
+ </row>
+ <row>
+ <entry><literal>mmm.dd.yyyy</literal></entry>
+ <entry><literal>9/14/58</literal></entry>
+ <entry><literal>1958-09-14</literal></entry>
+ </row>
+ <row>
+ <entry><literal>yy/mm/dd</literal></entry>
+ <entry><literal>47/03/29</literal></entry>
+ <entry><literal>1947-03-29</literal></entry>
+ </row>
+ <row>
+ <entry><literal>mmm.dd.yyyy</literal></entry>
+ <entry><literal>oct 28 1975</literal></entry>
+ <entry><literal>1975-10-28</literal></entry>
+ </row>
+ <row>
+ <entry><literal>mmddyy</literal></entry>
+ <entry><literal>Nov 14th, 1985</literal></entry>
+ <entry><literal>1985-11-14</literal></entry>
+ </row>
</tbody>
</tgroup>
</table>
<term><function>PGTYPEStimestamp_from_asc</function></term>
<listitem>
<para>
- Parse a timestamp from its textual representation into a timestamp
- variable.
+ Parse a timestamp from its textual representation into a timestamp
+ variable.
<synopsis>
timestamp PGTYPEStimestamp_from_asc(char *str, char **endptr);
</synopsis>
- The function receives the string to parse (<literal>str</>) and a
- pointer to a C char* (<literal>endptr</>).
- At the moment ecpg always parses
- the complete string and so it currently does not support to store the
- address of the first invalid character in <literal>*endptr</literal>.
- You can safely set <literal>endptr</literal> to NULL.
+ The function receives the string to parse (<literal>str</>) and a
+ pointer to a C char* (<literal>endptr</>).
+ At the moment ecpg always parses
+ the complete string and so it currently does not support to store the
+ address of the first invalid character in <literal>*endptr</literal>.
+ You can safely set <literal>endptr</literal> to NULL.
</para>
<para>
- The function returns the parsed timestamp on success. On error,
- <literal>PGTYPESInvalidTimestamp</literal> is returned and errno is
- set to <literal>PGTYPES_TS_BAD_TIMESTAMP</>. See <xref linkend="PGTYPESInvalidTimestamp"> for important notes on this value.
-
+ The function returns the parsed timestamp on success. On error,
+ <literal>PGTYPESInvalidTimestamp</literal> is returned and errno is
+ set to <literal>PGTYPES_TS_BAD_TIMESTAMP</>. See <xref linkend="PGTYPESInvalidTimestamp"> for important notes on this value.
+
</para>
<para>
- In general, the input string can contain any combination of an allowed
- date specification, a whitespace character and an allowed time
- specification. Note that timezones are not supported by ecpg. It can
- parse them but does not apply any calculation as the
- <productname>PostgreSQL</> server does for example. Timezone
- specifiers are silently discarded.
+ In general, the input string can contain any combination of an allowed
+ date specification, a whitespace character and an allowed time
+ specification. Note that timezones are not supported by ecpg. It can
+ parse them but does not apply any calculation as the
+
<productname>PostgreSQL</> server does for example. Timezone
+ specifiers are silently discarded.
</para>
<para>
The following table contains a few examples for input strings:
<table>
- <title>Valid input formats for <function>PGTYPEStimestamp_from_asc</function></title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Input</entry>
- <entry>Result</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>1999-01-08 04:05:06</literal></entry>
- <entry><literal>1999-01-08 04:05:06</literal></entry>
- </row>
- <row>
- <entry><literal>January 8 04:05:06 1999 PST</literal></entry>
- <entry><literal>1999-01-08 04:05:06</literal></entry>
- </row>
- <row>
- <entry><literal>1999-Jan-08 04:05:06.789-8</literal></entry>
- <entry><literal>1999-01-08 04:05:06.789 (time zone specifier ignored)</literal></entry>
- </row>
- <row>
- <entry><literal>J2451187 04:05-08:00</literal></entry>
- <entry><literal>1999-01-08 04:05:00 (time zone specifier ignored)</literal></entry>
- </row>
+ <title>Valid input formats for <function>PGTYPEStimestamp_from_asc</function></title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Input</entry>
+ <entry>Result</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>1999-01-08 04:05:06</literal></entry>
+ <entry><literal>1999-01-08 04:05:06</literal></entry>
+ </row>
+ <row>
+ <entry><literal>January 8 04:05:06 1999 PST</literal></entry>
+ <entry><literal>1999-01-08 04:05:06</literal></entry>
+ </row>
+ <row>
+ <entry><literal>1999-Jan-08 04:05:06.789-8</literal></entry>
+ <entry><literal>1999-01-08 04:05:06.789 (time zone specifier ignored)</literal></entry>
+ </row>
+ <row>
+ <entry><literal>J2451187 04:05-08:00</literal></entry>
+ <entry><literal>1999-01-08 04:05:00 (time zone specifier ignored)</literal></entry>
+ </row>
</tbody>
</tgroup>
</table>
<synopsis>
char *PGTYPEStimestamp_to_asc(timestamp tstamp);
</synopsis>
- The function receives the timestamp <literal>tstamp</> as
- its only argument and returns an allocated string that contains the
- textual representation of the timestamp.
+ The function receives the timestamp <literal>tstamp</> as
+ its only argument and returns an allocated string that contains the
+ textual representation of the timestamp.
</para>
</listitem>
</varlistentry>
<synopsis>
void PGTYPEStimestamp_current(timestamp *ts);
</synopsis>
- The function retrieves the current timestamp and saves it into the
- timestamp variable that <literal>ts</> points to.
+ The function retrieves the current timestamp and saves it into the
+ timestamp variable that <literal>ts</> points to.
</para>
</listitem>
</varlistentry>
<synopsis>
int PGTYPEStimestamp_fmt_asc(timestamp *ts, char *output, int str_len, char *fmtstr);
</synopsis>
- The function receives a pointer to the timestamp to convert as its
- first argument (<literal>ts</>), a pointer to the output buffer
- (<literal>output</>), the maximal length that has been allocated for
- the output buffer (<literal>str_len</literal>) and the format mask to
- use for the conversion (<literal>fmtstr</literal>).
+ The function receives a pointer to the timestamp to convert as its
+ first argument (<literal>ts</>), a pointer to the output buffer
+ (<literal>output</>), the maximal length that has been allocated for
+ the output buffer (<literal>str_len</literal>) and the format mask to
+ use for the conversion (<literal>fmtstr</literal>).
</para>
<para>
- Upon success, the function returns 0 and a negative value if an
- error occurred.
+ Upon success, the function returns 0 and a negative value if an
+ error occurred.
</para>
<para>
- You can use the following format specifiers for the format mask. The
- format specifiers are the same ones that are used in the
- <function>strftime</> function in <productname>libc</productname>. Any
- non-format specifier will be copied into the output buffer.
- <!-- This is from the FreeBSD man page:
- http://www.freebsd.org/cgi/man.cgi?query=strftime&apropos=0&sektion=3&manpath=FreeBSD+7.0-current&format=html
- -->
+ You can use the following format specifiers for the format mask. The
+ format specifiers are the same ones that are used in the
+
<function>strftime</> function in <productname>libc</productname>. Any
+ non-format specifier will be copied into the output buffer.
+ <!-- This is from the FreeBSD man page:
+ http://www.freebsd.org/cgi/man.cgi?query=strftime&apropos=0&sektion=3&manpath=FreeBSD+7.0-current&format=html
+ -->
<itemizedlist>
<listitem>
<para>
- <literal>%A</literal> - is replaced by national representation of
- the full weekday name.
+ <literal>%A</literal> - is replaced by national representation of
+ the full weekday name.
</para>
</listitem>
<listitem>
<para>
- <literal>%a</literal> - is replaced by national representation of
- the abbreviated weekday name.
+ <literal>%a</literal> - is replaced by national representation of
+ the abbreviated weekday name.
</para>
</listitem>
<listitem>
<para>
- <literal>%B</literal> - is replaced by national representation of
- the full month name.
+ <literal>%B</literal> - is replaced by national representation of
+ the full month name.
</para>
</listitem>
<listitem>
<para>
- <literal>%b</literal> - is replaced by national representation of
- the abbreviated month name.
+ <literal>%b</literal> - is replaced by national representation of
+ the abbreviated month name.
</para>
</listitem>
<listitem>
<para>
- <literal>%C</literal> - is replaced by (year / 100) as decimal
- number; single digits are preceded by a zero.
+ <literal>%C</literal> - is replaced by (year / 100) as decimal
+ number; single digits are preceded by a zero.
</para>
</listitem>
<listitem>
<para>
- <literal>%c</literal> - is replaced by national representation of
- time and date.
+ <literal>%c</literal> - is replaced by national representation of
+ time and date.
</para>
</listitem>
<listitem>
<para>
- <literal>%D</literal> - is equivalent to
- <literal>%m/%d/%y</literal>.
+ <literal>%D</literal> - is equivalent to
+ <literal>%m/%d/%y</literal>.
</para>
</listitem>
<listitem>
<para>
- <literal>%d</literal> - is replaced by the day of the month as a
- decimal number (01-31).
+ <literal>%d</literal> - is replaced by the day of the month as a
+ decimal number (01-31).
</para>
</listitem>
<listitem>
<para>
- <literal>%E*</literal> <literal>%O*</literal> - POSIX locale
- extensions. The sequences
- <literal>%Ec</literal>
- <literal>%EC</literal>
- <literal>%Ex</literal>
- <literal>%EX</literal>
- <literal>%Ey</literal>
- <literal>%EY</literal>
- <literal>%Od</literal>
- <literal>%Oe</literal>
- <literal>%OH</literal>
- <literal>%OI</literal>
- <literal>%Om</literal>
- <literal>%OM</literal>
- <literal>%OS</literal>
- <literal>%Ou</literal>
- <literal>%OU</literal>
- <literal>%OV</literal>
- <literal>%Ow</literal>
- <literal>%OW</literal>
- <literal>%Oy</literal>
- are supposed to provide alternate representations.
+ <literal>%E*</literal> <literal>%O*</literal> - POSIX locale
+ extensions. The sequences
+ <literal>%Ec</literal>
+ <literal>%EC</literal>
+ <literal>%Ex</literal>
+ <literal>%EX</literal>
+ <literal>%Ey</literal>
+ <literal>%EY</literal>
+ <literal>%Od</literal>
+ <literal>%Oe</literal>
+ <literal>%OH</literal>
+ <literal>%OI</literal>
+ <literal>%Om</literal>
+ <literal>%OM</literal>
+ <literal>%OS</literal>
+ <literal>%Ou</literal>
+ <literal>%OU</literal>
+ <literal>%OV</literal>
+ <literal>%Ow</literal>
+ <literal>%OW</literal>
+ <literal>%Oy</literal>
+ are supposed to provide alternate representations.
</para>
<para>
- Additionally <literal>%OB</literal> implemented to represent
- alternative months names (used standalone, without day mentioned).
+ Additionally <literal>%OB</literal> implemented to represent
+ alternative months names (used standalone, without day mentioned).
</para>
</listitem>
<listitem>
<para>
- <literal>%e</literal> - is replaced by the day of month as a decimal
- number (1-31); single digits are preceded by a blank.
+ <literal>%e</literal> - is replaced by the day of month as a decimal
+ number (1-31); single digits are preceded by a blank.
</para>
</listitem>
<listitem>
<para>
- <literal>%F</literal> - is equivalent to <literal>%Y-%m-%d</literal>.
+ <literal>%F</literal> - is equivalent to <literal>%Y-%m-%d</literal>.
</para>
</listitem>
<listitem>
<para>
- <literal>%G</literal> - is replaced by a year as a decimal number
- with century. This year is the one that contains the greater part of
- the week (Monday as the first day of the week).
+ <literal>%G</literal> - is replaced by a year as a decimal number
+ with century. This year is the one that contains the greater part of
+ the week (Monday as the first day of the week).
</para>
</listitem>
<listitem>
<para>
- <literal>%g</literal> - is replaced by the same year as in
- <literal>%G</literal>, but as a decimal number without century
- (00-99).
+ <literal>%g</literal> - is replaced by the same year as in
+ <literal>%G</literal>, but as a decimal number without century
+ (00-99).
</para>
</listitem>
<listitem>
<para>
- <literal>%H</literal> - is replaced by the hour (24-hour clock) as a
- decimal number (00-23).
+ <literal>%H</literal> - is replaced by the hour (24-hour clock) as a
+ decimal number (00-23).
</para>
</listitem>
<listitem>
<para>
- <literal>%h</literal> - the same as <literal>%b</literal>.
+ <literal>%h</literal> - the same as <literal>%b</literal>.
</para>
</listitem>
<listitem>
<para>
- <literal>%I</literal> - is replaced by the hour (12-hour clock) as a
- decimal number (01-12).
+ <literal>%I</literal> - is replaced by the hour (12-hour clock) as a
+ decimal number (01-12).
</para>
</listitem>
<listitem>
<para>
- <literal>%j</literal> - is replaced by the day of the year as a
- decimal number (001-366).
+ <literal>%j</literal> - is replaced by the day of the year as a
+ decimal number (001-366).
</para>
</listitem>
<listitem>
<para>
- <literal>%k</literal> - is replaced by the hour (24-hour clock) as a
- decimal number (0-23); single digits are preceded by a blank.
+ <literal>%k</literal> - is replaced by the hour (24-hour clock) as a
+ decimal number (0-23); single digits are preceded by a blank.
</para>
</listitem>
<listitem>
<para>
- <literal>%l</literal> - is replaced by the hour (12-hour clock) as a
- decimal number (1-12); single digits are preceded by a blank.
+ <literal>%l</literal> - is replaced by the hour (12-hour clock) as a
+ decimal number (1-12); single digits are preceded by a blank.
</para>
</listitem>
<listitem>
<para>
- <literal>%M</literal> - is replaced by the minute as a decimal
- number (00-59).
+ <literal>%M</literal> - is replaced by the minute as a decimal
+ number (00-59).
</para>
</listitem>
<listitem>
<para>
- <literal>%m</literal> - is replaced by the month as a decimal number
- (01-12).
+ <literal>%m</literal> - is replaced by the month as a decimal number
+ (01-12).
</para>
</listitem>
<listitem>
<para>
- <literal>%n</literal> - is replaced by a newline.
+ <literal>%n</literal> - is replaced by a newline.
</para>
</listitem>
<listitem>
<para>
- <literal>%O*</literal> - the same as <literal>%E*</literal>.
+ <literal>%O*</literal> - the same as <literal>%E*</literal>.
</para>
</listitem>
<listitem>
<para>
- <literal>%p</literal> - is replaced by national representation of
- either "ante meridiem" or "post meridiem" as appropriate.
+ <literal>%p</literal> - is replaced by national representation of
+ either "ante meridiem" or "post meridiem" as appropriate.
</para>
</listitem>
<listitem>
<para>
- <literal>%R</literal> - is equivalent to <literal>%H:%M</literal>.
+ <literal>%R</literal> - is equivalent to <literal>%H:%M</literal>.
</para>
</listitem>
<listitem>
<para>
- <literal>%r</literal> - is equivalent to <literal>%I:%M:%S
- %p</literal>.
+ <literal>%r</literal> - is equivalent to <literal>%I:%M:%S
+ %p</literal>.
</para>
</listitem>
<listitem>
<para>
- <literal>%S</literal> - is replaced by the second as a decimal
- number (00-60).
+ <literal>%S</literal> - is replaced by the second as a decimal
+ number (00-60).
</para>
</listitem>
<listitem>
<para>
- <literal>%s</literal> - is replaced by the number of seconds since
- the Epoch, UTC.
+ <literal>%s</literal> - is replaced by the number of seconds since
+ the Epoch, UTC.
</para>
</listitem>
<listitem>
<para>
- <literal>%T</literal> - is equivalent to <literal>%H:%M:%S</literal>
+ <literal>%T</literal> - is equivalent to <literal>%H:%M:%S</literal>
</para>
</listitem>
<listitem>
<para>
- <literal>%t</literal> - is replaced by a tab.
+ <literal>%t</literal> - is replaced by a tab.
</para>
</listitem>
<listitem>
<para>
- <literal>%U</literal> - is replaced by the week number of the year
- (Sunday as the first day of the week) as a decimal number (00-53).
+ <literal>%U</literal> - is replaced by the week number of the year
+ (Sunday as the first day of the week) as a decimal number (00-53).
</para>
</listitem>
<listitem>
<para>
- <literal>%u</literal> - is replaced by the weekday (Monday as the
- first day of the week) as a decimal number (1-7).
+ <literal>%u</literal> - is replaced by the weekday (Monday as the
+ first day of the week) as a decimal number (1-7).
</para>
</listitem>
<listitem>
<para>
- <literal>%V</literal> - is replaced by the week number of the year
- (Monday as the first day of the week) as a decimal number (01-53).
- If the week containing January 1 has four or more days in the new
- year, then it is week 1; otherwise it is the last week of the
- previous year, and the next week is week 1.
+ <literal>%V</literal> - is replaced by the week number of the year
+ (Monday as the first day of the week) as a decimal number (01-53).
+ If the week containing January 1 has four or more days in the new
+ year, then it is week 1; otherwise it is the last week of the
+ previous year, and the next week is week 1.
</para>
</listitem>
<listitem>
<para>
- <literal>%v</literal> - is equivalent to
- <literal>%e-%b-%Y</literal>.
+ <literal>%v</literal> - is equivalent to
+ <literal>%e-%b-%Y</literal>.
</para>
</listitem>
<listitem>
<para>
- <literal>%W</literal> - is replaced by the week number of the year
- (Monday as the first day of the week) as a decimal number (00-53).
+ <literal>%W</literal> - is replaced by the week number of the year
+ (Monday as the first day of the week) as a decimal number (00-53).
</para>
</listitem>
<listitem>
<para>
- <literal>%w</literal> - is replaced by the weekday (Sunday as the
- first day of the week) as a decimal number (0-6).
+ <literal>%w</literal> - is replaced by the weekday (Sunday as the
+ first day of the week) as a decimal number (0-6).
</para>
</listitem>
<listitem>
<para>
- <literal>%X</literal> - is replaced by national representation of
- the time.
+ <literal>%X</literal> - is replaced by national representation of
+ the time.
</para>
</listitem>
<listitem>
<para>
- <literal>%x</literal> - is replaced by national representation of
- the date.
+ <literal>%x</literal> - is replaced by national representation of
+ the date.
</para>
</listitem>
<listitem>
<para>
- <literal>%Y</literal> - is replaced by the year with century as a
- decimal number.
+ <literal>%Y</literal> - is replaced by the year with century as a
+ decimal number.
</para>
</listitem>
<listitem>
<para>
- <literal>%y</literal> - is replaced by the year without century as a
- decimal number (00-99).
+ <literal>%y</literal> - is replaced by the year without century as a
+ decimal number (00-99).
</para>
</listitem>
<listitem>
<para>
- <literal>%Z</literal> - is replaced by the time zone name.
+ <literal>%Z</literal> - is replaced by the time zone name.
</para>
</listitem>
<listitem>
<para>
- <literal>%z</literal> - is replaced by the time zone offset from
- UTC; a leading plus sign stands for east of UTC, a minus sign for
- west of UTC, hours and minutes follow with two digits each and no
- delimiter between them (common form for RFC 822 date headers).
+ <literal>%z</literal> - is replaced by the time zone offset from
+ UTC; a leading plus sign stands for east of UTC, a minus sign for
+ west of UTC, hours and minutes follow with two digits each and no
+ delimiter between them (common form for RFC 822 date headers).
</para>
</listitem>
<listitem>
<para>
- <literal>%+</literal> - is replaced by national representation of
- the date and time.
+ <literal>%+</literal> - is replaced by national representation of
+ the date and time.
</para>
</listitem>
<listitem>
<para>
- <literal>%-*</literal> - GNU libc extension. Do not do any padding
- when performing numerical outputs.
+ <literal>%-*</literal> - GNU libc extension. Do not do any padding
+ when performing numerical outputs.
</para>
</listitem>
<listitem>
<para>
- $_* - GNU libc extension. Explicitly specify space for padding.
+ $_* - GNU libc extension. Explicitly specify space for padding.
</para>
</listitem>
<listitem>
<para>
- <literal>%0*</literal> - GNU libc extension. Explicitly specify zero
- for padding.
+ <literal>%0*</literal> - GNU libc extension. Explicitly specify zero
+ for padding.
</para>
</listitem>
<listitem>
<para>
- <literal>%%</literal> - is replaced by <literal>%</literal>.
+ <literal>%%</literal> - is replaced by <literal>%</literal>.
</para>
</listitem>
</itemizedlist>
<term><function>PGTYPEStimestamp_sub</function></term>
<listitem>
<para>
- Subtract one timestamp from another one and save the result in a
- variable of type interval.
+ Subtract one timestamp from another one and save the result in a
+ variable of type interval.
<synopsis>
int PGTYPEStimestamp_sub(timestamp *ts1, timestamp *ts2, interval *iv);
</synopsis>
- The function will subtract the timestamp variable that <literal>ts2</>
- points to from the timestamp variable that <literal>ts1</> points to
- and will store the result in the interval variable that <literal>iv</>
- points to.
+ The function will subtract the timestamp variable that <literal>ts2</>
+ points to from the timestamp variable that <literal>ts1</> points to
+ and will store the result in the interval variable that <literal>iv</>
+ points to.
</para>
<para>
- Upon success, the function returns 0 and a negative value if an
- error occurred.
+ Upon success, the function returns 0 and a negative value if an
+ error occurred.
</para>
</listitem>
</varlistentry>
<term><function>PGTYPEStimestamp_defmt_asc</function></term>
<listitem>
<para>
- Parse a timestamp value from its textual representation using a
- formatting mask.
+ Parse a timestamp value from its textual representation using a
+ formatting mask.
<synopsis>
int PGTYPEStimestamp_defmt_asc(char *str, char *fmt, timestamp *d);
</synopsis>
- The function receives the textual representation of a timestamp in the
- variable <literal>str</> as well as the formatting mask to use in the
- variable <literal>fmt</>. The result will be stored in the variable
- that <literal>d</> points to.
+ The function receives the textual representation of a timestamp in the
+ variable <literal>str</> as well as the formatting mask to use in the
+ variable <literal>fmt</>. The result will be stored in the variable
+ that <literal>d</> points to.
</para>
<para>
- If the formatting mask <literal>fmt</> is NULL, the function will fall
- back to the default formatting mask which is <literal>%Y-%m-%d
- %H:%M:%S</literal>.
+ If the formatting mask <literal>fmt</> is NULL, the function will fall
+ back to the default formatting mask which is <literal>%Y-%m-%d
+ %H:%M:%S</literal>.
</para>
<para>
- This is the reverse function to <xref
- linkend="PGTYPEStimestampfmtasc">. See the documentation there in
- order to find out about the possible formatting mask entries.
+ This is the reverse function to <xref
+ linkend="PGTYPEStimestampfmtasc">. See the documentation there in
+ order to find out about the possible formatting mask entries.
</para>
</listitem>
</varlistentry>
<synopsis>
int PGTYPEStimestamp_add_interval(timestamp *tin, interval *span, timestamp *tout);
</synopsis>
- The function receives a pointer to a timestamp variable <literal>tin</>
- and a pointer to an interval variable <literal>span</>. It adds the
- interval to the timestamp and saves the resulting timestamp in the
- variable that <literal>tout</> points to.
+ The function receives a pointer to a timestamp variable <literal>tin</>
+ and a pointer to an interval variable <literal>span</>. It adds the
+ interval to the timestamp and saves the resulting timestamp in the
+ variable that <literal>tout</> points to.
</para>
<para>
- Upon success, the function returns 0 and a negative value if an
- error occurred.
+ Upon success, the function returns 0 and a negative value if an
+ error occurred.
</para>
</listitem>
</varlistentry>
<synopsis>
int PGTYPEStimestamp_sub_interval(timestamp *tin, interval *span, timestamp *tout);
</synopsis>
- The function subtracts the interval variable that <literal>span</>
- points to from the timestamp variable that <literal>tin</> points to
- and saves the result into the variable that <literal>tout</> points
- to.
+ The function subtracts the interval variable that <literal>span</>
+ points to from the timestamp variable that <literal>tin</> points to
+ and saves the result into the variable that <literal>tout</> points
+ to.
</para>
<para>
- Upon success, the function returns 0 and a negative value if an
- error occurred.
+ Upon success, the function returns 0 and a negative value if an
+ error occurred.
</para>
</listitem>
</varlistentry>
<synopsis>
interval *PGTYPESinterval_from_asc(char *str, char **endptr);
</synopsis>
- The function parses the input string <literal>str</> and returns a
- pointer to an allocated interval variable.
- At the moment ecpg always parses
- the complete string and so it currently does not support to store the
- address of the first invalid character in <literal>*endptr</literal>.
- You can safely set <literal>endptr</literal> to NULL.
+ The function parses the input string <literal>str</> and returns a
+ pointer to an allocated interval variable.
+ At the moment ecpg always parses
+ the complete string and so it currently does not support to store the
+ address of the first invalid character in <literal>*endptr</literal>.
+ You can safely set <literal>endptr</literal> to NULL.
</para>
</listitem>
</varlistentry>
<synopsis>
char *PGTYPESinterval_to_asc(interval *span);
</synopsis>
- The function converts the interval variable that <literal>span</>
- points to into a C char*. The output looks like this example:
- <literal>@ 1 day 12 hours 59 mins 10 secs</literal>.
+ The function converts the interval variable that <literal>span</>
+ points to into a C char*. The output looks like this example:
+ <literal>@ 1 day 12 hours 59 mins 10 secs</literal>.
</para>
</listitem>
</varlistentry>
<synopsis>
int PGTYPESinterval_copy(interval *intvlsrc, interval *intvldest);
</synopsis>
- The function copies the interval variable that <literal>intvlsrc</>
- points to into the variable that <literal>intvldest</> points to. Note
- that you need to allocate the memory for the destination variable
- before.
+ The function copies the interval variable that <literal>intvlsrc</>
+ points to into the variable that <literal>intvldest</> points to. Note
+ that you need to allocate the memory for the destination variable
+ before.
</para>
</listitem>
</varlistentry>
<term><literal>PGTYPES_NUM_BAD_NUMERIC</literal></term>
<listitem>
<para>
- An argument should contain a numeric variable (or point to a numeric
- variable) but in fact its in-memory representation was invalid.
+ An argument should contain a numeric variable (or point to a numeric
+ variable) but in fact its in-memory representation was invalid.
</para>
</listitem>
</varlistentry>
<term><literal>PGTYPES_NUM_OVERFLOW</literal></term>
<listitem>
<para>
- An overflow occurred. Since the numeric type can deal with almost
- arbitrary precision, converting a numeric variable into other types
- might cause overflow.
+ An overflow occurred. Since the numeric type can deal with almost
+ arbitrary precision, converting a numeric variable into other types
+ might cause overflow.
</para>
</listitem>
</varlistentry>
<term><literal>PGTYPES_NUM_OVERFLOW</literal></term>
<listitem>
<para>
- An underflow occurred. Since the numeric type can deal with almost
- arbitrary precision, converting a numeric variable into other types
- might cause underflow.
+ An underflow occurred. Since the numeric type can deal with almost
+ arbitrary precision, converting a numeric variable into other types
+ might cause underflow.
</para>
</listitem>
</varlistentry>
<term><literal>PGTYPESInvalidTimestamp</literal></term>
<listitem>
<para>
- A value of type timestamp representing an invalid time stamp. This is
- returned by the function <function>PGTYPEStimestamp_from_asc</> on
- parse error.
- Note that due to the internal representation of the timestamp datatype,
- <literal>PGTYPESInvalidTimestamp</literal> is also a valid timestamp at
- the same time. It is set to <literal>1899-12-31 23:59:59</>. In order
- to detect errors, make sure that your application does not only test
- for <literal>PGTYPESInvalidTimestamp</literal> but also for
- <literal>errno != 0</> after each call to
- <function>PGTYPEStimestamp_from_asc</>.
+ A value of type timestamp representing an invalid time stamp. This is
+ returned by the function <function>PGTYPEStimestamp_from_asc</> on
+ parse error.
+ Note that due to the internal representation of the timestamp datatype,
+ <literal>PGTYPESInvalidTimestamp</literal> is also a valid timestamp at
+ the same time. It is set to <literal>1899-12-31 23:59:59</>. In order
+ to detect errors, make sure that your application does not only test
+ for <literal>PGTYPESInvalidTimestamp</literal> but also for
+ <literal>errno != 0</> after each call to
+ <function>PGTYPEStimestamp_from_asc</>.
</para>
</listitem>
</varlistentry>
<term><literal>CLOSE DATABASE</></term>
<listitem>
<para>
- This statement closes the current connection. In fact, this is a
- synonym for ecpg's <literal>DISCONNECT CURRENT</>.:
+ This statement closes the current connection. In fact, this is a
+ synonym for ecpg's <literal>DISCONNECT CURRENT</>.:
<programlisting>
$CLOSE DATABASE; /* close the current connection */
EXEC SQL CLOSE DATABASE;
<synopsis>
int decadd(decimal *arg1, decimal *arg2, decimal *sum);
</synopsis>
- The function receives a pointer to the first operand of type decimal
- (<literal>arg1</>), a pointer to the second operand of type decimal
- (<literal>arg2</>) and a pointer to a value of type decimal that will
- contain the sum (<literal>sum</>). On success, the function returns 0.
- ECPG_INFORMIX_NUM_OVERFLOW is returned in case of overflow and
- ECPG_INFORMIX_NUM_UNDERFLOW in case of underflow. -1 is returned for
- other failures and errno is set to the respective errno number of the
- pgtypeslib.
+ The function receives a pointer to the first operand of type decimal
+ (<literal>arg1</>), a pointer to the second operand of type decimal
+ (<literal>arg2</>) and a pointer to a value of type decimal that will
+ contain the sum (<literal>sum</>). On success, the function returns 0.
+ ECPG_INFORMIX_NUM_OVERFLOW is returned in case of overflow and
+ ECPG_INFORMIX_NUM_UNDERFLOW in case of underflow. -1 is returned for
+ other failures and errno is set to the respective errno number of the
+ pgtypeslib.
</para>
</listitem>
</varlistentry>
<synopsis>
int deccmp(decimal *arg1, decimal *arg2);
</synopsis>
- The function receives a pointer to the first decimal value
- (<literal>arg1</>), a pointer to the second decimal value
- (<literal>arg2</>) and returns an integer value that indicates which is
- the bigger value.
+ The function receives a pointer to the first decimal value
+ (<literal>arg1</>), a pointer to the second decimal value
+ (<literal>arg2</>) and returns an integer value that indicates which is
+ the bigger value.
<itemizedlist>
<listitem>
<para>
- 1, if the value that <literal>arg1</> points to is bigger than the
- value that <literal>var2</> points to
+ 1, if the value that <literal>arg1</> points to is bigger than the
+ value that <literal>var2</> points to
</para>
</listitem>
<listitem>
<para>
- -1, if the value that <literal>arg1</> points to is smaller than the
- value that <literal>arg2</> points to </para>
+ -1, if the value that <literal>arg1</> points to is smaller than the
+ value that <literal>arg2</> points to </para>
</listitem>
<listitem>
<para>
- 0, if the value that <literal>arg1</> points to and the value that
- <literal>arg2</> points to are equal
+ 0, if the value that <literal>arg1</> points to and the value that
+ <literal>arg2</> points to are equal
</para>
</listitem>
</itemizedlist>
<synopsis>
void deccopy(decimal *src, decimal *target);
</synopsis>
- The function receives a pointer to the decimal value that should be
- copied as the first argument (<literal>src</>) and a pointer to the
- target structure of type decimal (<literal>target</>) as the second
- argument.
+ The function receives a pointer to the decimal value that should be
+ copied as the first argument (<literal>src</>) and a pointer to the
+ target structure of type decimal (<literal>target</>) as the second
+ argument.
</para>
</listitem>
</varlistentry>
<synopsis>
int deccvasc(char *cp, int len, decimal *np);
</synopsis>
- The function receives a pointer to string that contains the string
- representation of the number to be converted (<literal>cp</>) as well
- as its length <literal>len</>. <literal>np</> is a pointer to the
- decimal value that saves the result of the operation.
+ The function receives a pointer to string that contains the string
+ representation of the number to be converted (<literal>cp</>) as well
+ as its length <literal>len</>. <literal>np</> is a pointer to the
+ decimal value that saves the result of the operation.
</para>
<para>
Valid formats are for example:
<literal>-32.84e-4</literal>.
</para>
<para>
- The function returns 0 on success. If overflow or underflow occurred,
- <literal>ECPG_INFORMIX_NUM_OVERFLOW</> or
- <literal>ECPG_INFORMIX_NUM_UNDERFLOW</> is returned. If the ASCII
- representation could not be parsed,
- <literal>ECPG_INFORMIX_BAD_NUMERIC</> is returned or
- <literal>ECPG_INFORMIX_BAD_EXPONENT</> if this problem occurred while
- parsing the exponent.
+ The function returns 0 on success. If overflow or underflow occurred,
+ <literal>ECPG_INFORMIX_NUM_OVERFLOW</> or
+ <literal>ECPG_INFORMIX_NUM_UNDERFLOW</> is returned. If the ASCII
+ representation could not be parsed,
+ <literal>ECPG_INFORMIX_BAD_NUMERIC</> is returned or
+ <literal>ECPG_INFORMIX_BAD_EXPONENT</> if this problem occurred while
+ parsing the exponent.
</para>
</listitem>
</varlistentry>
<synopsis>
int deccvdbl(double dbl, decimal *np);
</synopsis>
- The function receives the variable of type double that should be
- converted as its first argument (<literal>dbl</>). As the second
- argument (<literal>np</>), the function receives a pointer to the
- decimal variable that should hold the result of the operation.
+ The function receives the variable of type double that should be
+ converted as its first argument (<literal>dbl</>). As the second
+ argument (<literal>np</>), the function receives a pointer to the
+ decimal variable that should hold the result of the operation.
</para>
<para>
- The function returns 0 on success and a negative value if the
- conversion failed.
+ The function returns 0 on success and a negative value if the
+ conversion failed.
</para>
</listitem>
</varlistentry>
<synopsis>
int deccvint(int in, decimal *np);
</synopsis>
- The function receives the variable of type int that should be
- converted as its first argument (<literal>in</>). As the second
- argument (<literal>np</>), the function receives a pointer to the
- decimal variable that should hold the result of the operation.
+ The function receives the variable of type int that should be
+ converted as its first argument (<literal>in</>). As the second
+ argument (<literal>np</>), the function receives a pointer to the
+ decimal variable that should hold the result of the operation.
</para>
<para>
- The function returns 0 on success and a negative value if the
- conversion failed.
+ The function returns 0 on success and a negative value if the
+ conversion failed.
</para>
</listitem>
</varlistentry>
<synopsis>
int deccvlong(long lng, decimal *np);
</synopsis>
- The function receives the variable of type long that should be
- converted as its first argument (<literal>lng</>). As the second
- argument (<literal>np</>), the function receives a pointer to the
- decimal variable that should hold the result of the operation.
+ The function receives the variable of type long that should be
+ converted as its first argument (<literal>lng</>). As the second
+ argument (<literal>np</>), the function receives a pointer to the
+ decimal variable that should hold the result of the operation.
</para>
<para>
- The function returns 0 on success and a negative value if the
- conversion failed.
+ The function returns 0 on success and a negative value if the
+ conversion failed.
</para>
</listitem>
</varlistentry>
<synopsis>
int decdiv(decimal *n1, decimal *n2, decimal *result);
</synopsis>
- The function receives pointers to the variables that are the first
- (<literal>n1</>) and the second (<literal>n2</>) operands and
- calculates <literal>n1</>/<literal>n2</>. <literal>result</> is a
- pointer to the variable that should hold the result of the operation.
+ The function receives pointers to the variables that are the first
+ (<literal>n1</>) and the second (<literal>n2</>) operands and
+ calculates <literal>n1</>/<literal>n2</>. <literal>result</> is a
+ pointer to the variable that should hold the result of the operation.
</para>
<para>
- On success, 0 is returned and a negative value if the division fails.
- If overflow or underflow occurred, the function returns
- <literal>ECPG_INFORMIX_NUM_OVERFLOW</> or
- <literal>ECPG_INFORMIX_NUM_UNDERFLOW</> respectively. If an attempt to
- divide by zero is observed, the function returns
- <literal>ECPG_INFORMIX_DIVIDE_ZERO</literal>.
+ On success, 0 is returned and a negative value if the division fails.
+ If overflow or underflow occurred, the function returns
+ <literal>ECPG_INFORMIX_NUM_OVERFLOW</> or
+ <literal>ECPG_INFORMIX_NUM_UNDERFLOW</> respectively. If an attempt to
+ divide by zero is observed, the function returns
+ <literal>ECPG_INFORMIX_DIVIDE_ZERO</literal>.
</para>
</listitem>
</varlistentry>
<synopsis>
int decmul(decimal *n1, decimal *n2, decimal *result);
</synopsis>
- The function receives pointers to the variables that are the first
- (<literal>n1</>) and the second (<literal>n2</>) operands and
- calculates <literal>n1</>*<literal>n2</>. <literal>result</> is a
- pointer to the variable that should hold the result of the operation.
+ The function receives pointers to the variables that are the first
+ (<literal>n1</>) and the second (<literal>n2</>) operands and
+ calculates <literal>n1</>*<literal>n2</>. <literal>result</> is a
+ pointer to the variable that should hold the result of the operation.
</para>
<para>
- On success, 0 is returned and a negative value if the multiplication
- fails. If overflow or underflow occurred, the function returns
- <literal>ECPG_INFORMIX_NUM_OVERFLOW</> or
- <literal>ECPG_INFORMIX_NUM_UNDERFLOW</> respectively.
+ On success, 0 is returned and a negative value if the multiplication
+ fails. If overflow or underflow occurred, the function returns
+ <literal>ECPG_INFORMIX_NUM_OVERFLOW</> or
+ <literal>ECPG_INFORMIX_NUM_UNDERFLOW</> respectively.
</para>
</listitem>
</varlistentry>
<synopsis>
int decsub(decimal *n1, decimal *n2, decimal *result);
</synopsis>
- The function receives pointers to the variables that are the first
- (<literal>n1</>) and the second (<literal>n2</>) operands and
- calculates <literal>n1</>-<literal>n2</>. <literal>result</> is a
- pointer to the variable that should hold the result of the operation.
+ The function receives pointers to the variables that are the first
+ (<literal>n1</>) and the second (<literal>n2</>) operands and
+ calculates <literal>n1</>-<literal>n2</>. <literal>result</> is a
+ pointer to the variable that should hold the result of the operation.
</para>
<para>
- On success, 0 is returned and a negative value if the subtraction
- fails. If overflow or underflow occurred, the function returns
- <literal>ECPG_INFORMIX_NUM_OVERFLOW</> or
- <literal>ECPG_INFORMIX_NUM_UNDERFLOW</> respectively.
+ On success, 0 is returned and a negative value if the subtraction
+ fails. If overflow or underflow occurred, the function returns
+ <literal>ECPG_INFORMIX_NUM_OVERFLOW</> or
+ <literal>ECPG_INFORMIX_NUM_UNDERFLOW</> respectively.
</para>
</listitem>
</varlistentry>
<term><function>dectoasc</></term>
<listitem>
<para>
- Convert a variable of type decimal to its ASCII representation in a C
- char* string.
+ Convert a variable of type decimal to its ASCII representation in a C
+ char* string.
<synopsis>
int dectoasc(decimal *np, char *cp, int len, int right)
</synopsis>
- The function receives a pointer to a variable of type decimal
- (<literal>np</>) that it converts to its textual representation.
- <literal>cp</> is the buffer that should hold the result of the
- operation. The parameter <literal>right</> specifies, how many digits
- right of the decimal point should be included in the output. The result
- will be rounded to this number of decimal digits. Setting
- <literal>right</> to -1 indicates that all available decimal digits
- should be included in the output. If the length of the output buffer,
- which is indicated by <literal>len</> is not sufficient to hold the
- textual representation including the trailing NUL character, only a
- single <literal>*</> character is stored in the result and -1 is
- returned.
- </para>
- <para>
- The function returns either -1 if the buffer <literal>cp</> was too
- small or <literal>ECPG_INFORMIX_OUT_OF_MEMORY</> if memory was
- exhausted.
+ The function receives a pointer to a variable of type decimal
+ (<literal>np</>) that it converts to its textual representation.
+ <literal>cp</> is the buffer that should hold the result of the
+ operation. The parameter <literal>right</> specifies, how many digits
+ right of the decimal point should be included in the output. The result
+ will be rounded to this number of decimal digits. Setting
+ <literal>right</> to -1 indicates that all available decimal digits
+ should be included in the output. If the length of the output buffer,
+ which is indicated by <literal>len</> is not sufficient to hold the
+ textual representation including the trailing NUL character, only a
+ single <literal>*</> character is stored in the result and -1 is
+ returned.
+ </para>
+ <para>
+ The function returns either -1 if the buffer <literal>cp</> was too
+ small or <literal>ECPG_INFORMIX_OUT_OF_MEMORY</> if memory was
+ exhausted.
</para>
</listitem>
</varlistentry>
<synopsis>
int dectodbl(decimal *np, double *dblp);
</synopsis>
- The function receives a pointer to the decimal value to convert
- (<literal>np</>) and a pointer to the double variable that
- should hold the result of the operation (<literal>dblp</>).
+ The function receives a pointer to the decimal value to convert
+ (<literal>np</>) and a pointer to the double variable that
+ should hold the result of the operation (<literal>dblp</>).
</para>
<para>
- On success, 0 is returned and a negative value if the conversion
- failed.
+ On success, 0 is returned and a negative value if the conversion
+ failed.
</para>
</listitem>
</varlistentry>
<synopsis>
int dectoint(decimal *np, int *ip);
</synopsis>
- The function receives a pointer to the decimal value to convert
- (<literal>np</>) and a pointer to the integer variable that
- should hold the result of the operation (<literal>ip</>).
+ The function receives a pointer to the decimal value to convert
+ (<literal>np</>) and a pointer to the integer variable that
+ should hold the result of the operation (<literal>ip</>).
</para>
<para>
- On success, 0 is returned and a negative value if the conversion
- failed. If an overflow occurred, <literal>ECPG_INFORMIX_NUM_OVERFLOW</>
- is returned.
+ On success, 0 is returned and a negative value if the conversion
+ failed. If an overflow occurred, <literal>ECPG_INFORMIX_NUM_OVERFLOW</>
+ is returned.
</para>
<para>
- Note that the ecpg implementation differs from the <productname>Informix</productname>
- implementation. <productname>Informix</productname> limits an integer to the range from -32767 to
- 32767, while the limits in the ecpg implementation depend on the
- architecture (<literal>-INT_MAX .. INT_MAX</>).
+
Note that the ecpg implementation differs from the <productname>Informix</productname>
+
implementation. <productname>Informix</productname> limits an integer to the range from -32767 to
+ 32767, while the limits in the ecpg implementation depend on the
+ architecture (<literal>-INT_MAX .. INT_MAX</>).
</para>
</listitem>
</varlistentry>
<synopsis>
int dectolong(decimal *np, long *lngp);
</synopsis>
- The function receives a pointer to the decimal value to convert
- (<literal>np</>) and a pointer to the long variable that
- should hold the result of the operation (<literal>lngp</>).
+ The function receives a pointer to the decimal value to convert
+ (<literal>np</>) and a pointer to the long variable that
+ should hold the result of the operation (<literal>lngp</>).
</para>
<para>
- On success, 0 is returned and a negative value if the conversion
- failed. If an overflow occurred, <literal>ECPG_INFORMIX_NUM_OVERFLOW</>
- is returned.
+ On success, 0 is returned and a negative value if the conversion
+ failed. If an overflow occurred, <literal>ECPG_INFORMIX_NUM_OVERFLOW</>
+ is returned.
</para>
<para>
- Note that the ecpg implementation differs from the <productname>Informix</productname>
- implementation. <productname>Informix</productname> limits a long integer to the range from
- -2,147,483,647 to 2,147,483,647, while the limits in the ecpg
- implementation depend on the architecture (<literal>-LONG_MAX ..
- LONG_MAX</>).
+
Note that the ecpg implementation differs from the <productname>Informix</productname>
+
implementation. <productname>Informix</productname> limits a long integer to the range from
+ -2,147,483,647 to 2,147,483,647, while the limits in the ecpg
+ implementation depend on the architecture (<literal>-LONG_MAX ..
+ LONG_MAX</>).
</para>
</listitem>
</varlistentry>
<synopsis>
int rdatestr(date d, char *str);
</synopsis>
- The function receives two arguments, the first one is the date to
- convert (<literal>d</> and the second one is a pointer to the target
- string. The output format is always <literal>yyyy-mm-dd</>, so you need
- to allocate at least 11 bytes (including the NUL-terminator) for the
- string.
+ The function receives two arguments, the first one is the date to
+ convert (<literal>d</> and the second one is a pointer to the target
+ string. The output format is always <literal>yyyy-mm-dd</>, so you need
+ to allocate at least 11 bytes (including the NUL-terminator) for the
+ string.
</para>
<para>
- The function returns 0 on success and a negative value in case of
- error.
+ The function returns 0 on success and a negative value in case of
+ error.
</para>
<para>
- Note that ecpg's implementation differs from the <productname>Informix</productname>
- implementation. In <productname>Informix</productname> the format can be influenced by setting
- environment variables. In ecpg however, you cannot change the output
- format.
+
Note that ecpg's implementation differs from the <productname>Informix</productname>
+
implementation. In <productname>Informix</productname> the format can be influenced by setting
+ environment variables. In ecpg however, you cannot change the output
+ format.
</para>
</listitem>
</varlistentry>
<synopsis>
int rstrdate(char *str, date *d);
</synopsis>
- The function receives the textual representation of the date to convert
- (<literal>str</>) and a pointer to a variable of type date
- (<literal>d</>). This function does not allow you to specify a format
- mask. It uses the default format mask of <productname>Informix</productname> which is
- <literal>mm/dd/yyyy</>. Internally, this function is implemented by
- means of <function>rdefmtdate</>. Therefore, <function>rstrdate</> is
- not faster and if you have the choice you should opt for
- <function>rdefmtdate</> which allows you to specify the format mask
- explicitly.
+ The function receives the textual representation of the date to convert
+ (<literal>str</>) and a pointer to a variable of type date
+ (<literal>d</>). This function does not allow you to specify a format
+
mask. It uses the default format mask of <productname>Informix</productname> which is
+ <literal>mm/dd/yyyy</>. Internally, this function is implemented by
+ means of <function>rdefmtdate</>. Therefore, <function>rstrdate</> is
+ not faster and if you have the choice you should opt for
+ <function>rdefmtdate</> which allows you to specify the format mask
+ explicitly.
</para>
<para>
The function returns the same values as <function>rdefmtdate</>.
<synopsis>
void rtoday(date *d);
</synopsis>
- The function receives a pointer to a date variable (<literal>d</>)
- that it sets to the current date.
+ The function receives a pointer to a date variable (<literal>d</>)
+ that it sets to the current date.
</para>
<para>
- Internally this function uses the <xref linkend="PGTYPESdatetoday">
- function.
+ Internally this function uses the <xref linkend="PGTYPESdatetoday">
+ function.
</para>
</listitem>
</varlistentry>
<term><function>rjulmdy</></term>
<listitem>
<para>
- Extract the values for the day, the month and the year from a variable
- of type date.
+ Extract the values for the day, the month and the year from a variable
+ of type date.
<synopsis>
int rjulmdy(date d, short mdy[3]);
</synopsis>
- The function receives the date <literal>d</> and a pointer to an array
- of 3 short integer values <literal>mdy</>. The variable name indicates
- the sequential order: <literal>mdy[0]</> will be set to contain the
- number of the month, <literal>mdy[1]</> will be set to the value of the
- day and <literal>mdy[2]</> will contain the year.
+ The function receives the date <literal>d</> and a pointer to an array
+ of 3 short integer values <literal>mdy</>. The variable name indicates
+ the sequential order: <literal>mdy[0]</> will be set to contain the
+ number of the month, <literal>mdy[1]</> will be set to the value of the
+ day and <literal>mdy[2]</> will contain the year.
</para>
<para>
The function always returns 0 at the moment.
</para>
<para>
- Internally the function uses the <xref linkend="PGTYPESdatejulmdy">
- function.
+ Internally the function uses the <xref linkend="PGTYPESdatejulmdy">
+ function.
</para>
</listitem>
</varlistentry>
<term><function>rdefmtdate</></term>
<listitem>
<para>
- Use a format mask to convert a character string to a value of type
- date.
+ Use a format mask to convert a character string to a value of type
+ date.
<synopsis>
int rdefmtdate(date *d, char *fmt, char *str);
</synopsis>
- The function receives a pointer to the date value that should hold the
- result of the operation (<literal>d</>), the format mask to use for
- parsing the date (<literal>fmt</>) and the C char* string containing
- the textual representation of the date (<literal>str</>). The textual
- representation is expected to match the format mask. However you do not
- need to have a 1:1 mapping of the string to the format mask. The
- function only analyzes the sequential order and looks for the literals
- <literal>yy</literal> or <literal>yyyy</literal> that indicate the
- position of the year, <literal>mm</literal> to indicate the position of
- the month and <literal>dd</literal> to indicate the position of the
- day.
+ The function receives a pointer to the date value that should hold the
+ result of the operation (<literal>d</>), the format mask to use for
+ parsing the date (<literal>fmt</>) and the C char* string containing
+ the textual representation of the date (<literal>str</>). The textual
+ representation is expected to match the format mask. However you do not
+ need to have a 1:1 mapping of the string to the format mask. The
+ function only analyzes the sequential order and looks for the literals
+ <literal>yy</literal> or <literal>yyyy</literal> that indicate the
+ position of the year, <literal>mm</literal> to indicate the position of
+ the month and <literal>dd</literal> to indicate the position of the
+ day.
</para>
<para>
The function returns the following values:
</listitem>
<listitem>
<para>
- <literal>ECPG_INFORMIX_ENOSHORTDATE</> - The date does not contain
- delimiters between day, month and year. In this case the input
- string must be exactly 6 or 8 bytes long but isn't.
+ <literal>ECPG_INFORMIX_ENOSHORTDATE</> - The date does not contain
+ delimiters between day, month and year. In this case the input
+ string must be exactly 6 or 8 bytes long but isn't.
</para>
</listitem>
<listitem>
<para>
- <literal>ECPG_INFORMIX_ENOTDMY</> - The format string did not
- correctly indicate the sequential order of year, month and day.
+ <literal>ECPG_INFORMIX_ENOTDMY</> - The format string did not
+ correctly indicate the sequential order of year, month and day.
</para>
</listitem>
<listitem>
<para>
- <literal>ECPG_INFORMIX_BAD_DAY</> - The input string does not
- contain a valid day.
+ <literal>ECPG_INFORMIX_BAD_DAY</> - The input string does not
+ contain a valid day.
</para>
</listitem>
<listitem>
<para>
- <literal>ECPG_INFORMIX_BAD_MONTH</> - The input string does not
- contain a valid month.
+ <literal>ECPG_INFORMIX_BAD_MONTH</> - The input string does not
+ contain a valid month.
</para>
</listitem>
<listitem>
<para>
- <literal>ECPG_INFORMIX_BAD_YEAR</> - The input string does not
- contain a valid year.
+ <literal>ECPG_INFORMIX_BAD_YEAR</> - The input string does not
+ contain a valid year.
</para>
</listitem>
- </itemizedlist>
+ </itemizedlist>
</para>
<para>
- Internally this function is implemented to use the <xref
- linkend="PGTYPESdatedefmtasc"> function. See the reference there for a
- table of example input.
+ Internally this function is implemented to use the <xref
+ linkend="PGTYPESdatedefmtasc"> function. See the reference there for a
+ table of example input.
</para>
</listitem>
</varlistentry>
<term><function>rfmtdate</></term>
<listitem>
<para>
- Convert a variable of type date to its textual representation using a
- format mask.
+ Convert a variable of type date to its textual representation using a
+ format mask.
<synopsis>
int rfmtdate(date d, char *fmt, char *str);
</synopsis>
- The function receives the date to convert (<literal>d</>), the format
- mask (<literal>fmt</>) and the string that will hold the textual
- representation of the date (<literal>str</>).
+ The function receives the date to convert (<literal>d</>), the format
+ mask (<literal>fmt</>) and the string that will hold the textual
+ representation of the date (<literal>str</>).
</para>
<para>
On success, 0 is returned and a negative value if an error occurred.
</para>
<para>
- Internally this function uses the <xref linkend="PGTYPESdatefmtasc">
- function, see the reference there for examples.
+ Internally this function uses the <xref linkend="PGTYPESdatefmtasc">
+ function, see the reference there for examples.
</para>
</listitem>
</varlistentry>
<term><function>rmdyjul</></term>
<listitem>
<para>
- Create a date value from an array of 3 short integers that specify the
- day, the month and the year of the date.
+ Create a date value from an array of 3 short integers that specify the
+ day, the month and the year of the date.
<synopsis>
int rmdyjul(short mdy[3], date *d);
</synopsis>
- The function receives the array of the 3 short integers
- (<literal>mdy</>) and a pointer to a variable of type date that should
- hold the result of the operation.
+ The function receives the array of the 3 short integers
+ (<literal>mdy</>) and a pointer to a variable of type date that should
+ hold the result of the operation.
</para>
<para>
Currently the function returns always 0.
</para>
<para>
- Internally the function is implemented to use the function <xref
- linkend="PGTYPESdatemdyjul">.
+ Internally the function is implemented to use the function <xref
+ linkend="PGTYPESdatemdyjul">.
</para>
</listitem>
</varlistentry>
<synopsis>
int rdayofweek(date d);
</synopsis>
- The function receives the date variable <literal>d</> as its only
- argument and returns an integer that indicates the day of the week for
- this date.
+ The function receives the date variable <literal>d</> as its only
+ argument and returns an integer that indicates the day of the week for
+ this date.
<itemizedlist>
<listitem>
<para>
- 0 - Sunday
+ 0 - Sunday
</para>
</listitem>
<listitem>
<para>
- 1 - Monday
+ 1 - Monday
</para>
</listitem>
<listitem>
<para>
- 2 - Tuesday
+ 2 - Tuesday
</para>
</listitem>
<listitem>
<para>
- 3 - Wednesday
+ 3 - Wednesday
</para>
</listitem>
<listitem>
<para>
- 4 - Thursday
+ 4 - Thursday
</para>
</listitem>
<listitem>
<para>
- 5 - Friday
+ 5 - Friday
</para>
</listitem>
<listitem>
<para>
- 6 - Saturday
+ 6 - Saturday
</para>
</listitem>
</itemizedlist>
</para>
<para>
- Internally the function is implemented to use the function <xref
- linkend="PGTYPESdatedayofweek">.
+ Internally the function is implemented to use the function <xref
+ linkend="PGTYPESdatedayofweek">.
</para>
</listitem>
</varlistentry>
<synopsis>
void dtcurrent(timestamp *ts);
</synopsis>
- The function retrieves the current timestamp and saves it into the
- timestamp variable that <literal>ts</> points to.
+ The function retrieves the current timestamp and saves it into the
+ timestamp variable that <literal>ts</> points to.
</para>
</listitem>
</varlistentry>
<term><function>dtcvasc</></term>
<listitem>
<para>
- Parses a timestamp from its textual representation in ANSI standard
- into a timestamp variable.
+ Parses a timestamp from its textual representation in ANSI standard
+ into a timestamp variable.
<synopsis>
int dtcvasc(char *str, timestamp *ts);
</synopsis>
- The function receives the string to parse (<literal>str</>) and a
- pointer to the timestamp variable that should hold the result of the
- operation (<literal>ts</>).
+ The function receives the string to parse (<literal>str</>) and a
+ pointer to the timestamp variable that should hold the result of the
+ operation (<literal>ts</>).
</para>
<para>
- The function returns 0 on success and a negative value in case of
- error.
+ The function returns 0 on success and a negative value in case of
+ error.
</para>
<para>
- Internally this function uses the <xref
- linkend="PGTYPEStimestampfromasc"> function. See the reference there
- for a table with example inputs.
+ Internally this function uses the <xref
+ linkend="PGTYPEStimestampfromasc"> function. See the reference there
+ for a table with example inputs.
</para>
</listitem>
</varlistentry>
<term><function>dtcvfmtasc</></term>
<listitem>
<para>
- Parses a timestamp from its textual representation in ANSI standard
- using a format mask into a timestamp variable.
+ Parses a timestamp from its textual representation in ANSI standard
+ using a format mask into a timestamp variable.
<synopsis>
dtcvfmtasc(char *inbuf, char *fmtstr, timestamp *dtvalue)
</synopsis>
- The function receives the string to parse (<literal>inbuf</>), the
- format mask to use (<literal>fmtstr</>) and a pointer to the timestamp
- variable that should hold the result of the operation (<literal>ts</>).
+ The function receives the string to parse (<literal>inbuf</>), the
+ format mask to use (<literal>fmtstr</>) and a pointer to the timestamp
+ variable that should hold the result of the operation (<literal>ts</>).
</para>
<para>
- This functions is implemented by means of the <xref
- linkend="PGTYPEStimestampdefmtasc">. See the documentation
- there for a list of format specifiers that can be used.
+ This functions is implemented by means of the <xref
+ linkend="PGTYPEStimestampdefmtasc">. See the documentation
+ there for a list of format specifiers that can be used.
</para>
<para>
- The function returns 0 on success and a negative value in case of
- error.
+ The function returns 0 on success and a negative value in case of
+ error.
</para>
</listitem>
</varlistentry>
<term><function>dtsub</></term>
<listitem>
<para>
- Subtract one timestamp from another and return a variable of type
- interval.
+ Subtract one timestamp from another and return a variable of type
+ interval.
<synopsis>
int dtsub(timestamp *ts1, timestamp *ts2, interval *iv);
</synopsis>
- The function will subtract the timestamp variable that <literal>ts2</>
- points to from the timestamp variable that <literal>ts1</> points to
- and will store the result in the interval variable that <literal>iv</>
- points to.
+ The function will subtract the timestamp variable that <literal>ts2</>
+ points to from the timestamp variable that <literal>ts1</> points to
+ and will store the result in the interval variable that <literal>iv</>
+ points to.
</para>
<para>
- Upon success, the function returns 0 and a negative value if an
- error occurred.
+ Upon success, the function returns 0 and a negative value if an
+ error occurred.
</para>
</listitem>
</varlistentry>
<synopsis>
int dttoasc(timestamp *ts, char *output);
</synopsis>
- The function receives a pointer to the timestamp variable to convert
- (<literal>ts</>) and the string that should hold the result of the
- operation <literal>output</>). It converts <literal>ts</> to its
- textual representation in the ANSI SQL standard which is defined to
- be <literal>YYYY-MM-DD HH:MM:SS</literal>.
+ The function receives a pointer to the timestamp variable to convert
+ (<literal>ts</>) and the string that should hold the result of the
+ operation <literal>output</>). It converts <literal>ts</> to its
+ textual representation in the ANSI SQL standard which is defined to
+ be <literal>YYYY-MM-DD HH:MM:SS</literal>.
</para>
<para>
- Upon success, the function returns 0 and a negative value if an
- error occurred.
+ Upon success, the function returns 0 and a negative value if an
+ error occurred.
</para>
</listitem>
</varlistentry>
<synopsis>
int dttofmtasc(timestamp *ts, char *output, int str_len, char *fmtstr);
</synopsis>
- The function receives a pointer to the timestamp to convert as its
- first argument (<literal>ts</>), a pointer to the output buffer
- (<literal>output</>), the maximal length that has been allocated for
- the output buffer (<literal>str_len</literal>) and the format mask to
- use for the conversion (<literal>fmtstr</literal>).
+ The function receives a pointer to the timestamp to convert as its
+ first argument (<literal>ts</>), a pointer to the output buffer
+ (<literal>output</>), the maximal length that has been allocated for
+ the output buffer (<literal>str_len</literal>) and the format mask to
+ use for the conversion (<literal>fmtstr</literal>).
</para>
<para>
- Upon success, the function returns 0 and a negative value if an
- error occurred.
+ Upon success, the function returns 0 and a negative value if an
+ error occurred.
</para>
<para>
- Internally, this function uses the <xref
- linkend="PGTYPEStimestampfmtasc"> function. See the reference there for
- information on what format mask specifiers can be used.
+ Internally, this function uses the <xref
+ linkend="PGTYPEStimestampfmtasc"> function. See the reference there for
+ information on what format mask specifiers can be used.
</para>
</listitem>
</varlistentry>
<synopsis>
int intoasc(interval *i, char *str);
</synopsis>
- The function receives a pointer to the interval variable to convert
- (<literal>i</>) and the string that should hold the result of the
- operation <literal>str</>). It converts <literal>i</> to its
- textual representation in the ANSI SQL standard which is defined to
- be <literal>YYYY-MM-DD HH:MM:SS</literal>.
+ The function receives a pointer to the interval variable to convert
+ (<literal>i</>) and the string that should hold the result of the
+ operation <literal>str</>). It converts <literal>i</> to its
+ textual representation in the ANSI SQL standard which is defined to
+ be <literal>YYYY-MM-DD HH:MM:SS</literal>.
</para>
<para>
- Upon success, the function returns 0 and a negative value if an
- error occurred.
+ Upon success, the function returns 0 and a negative value if an
+ error occurred.
</para>
</listitem>
</varlistentry>
<term><function>rfmtlong</></term>
<listitem>
<para>
- Convert a long integer value to its textual representation using a
- format mask.
+ Convert a long integer value to its textual representation using a
+ format mask.
<synopsis>
int rfmtlong(long lng_val, char *fmt, char *outbuf);
</synopsis>
- The function receives the long value <literal>lng_val</>, the format
- mask <literal>fmt</> and a pointer to the output buffer
- <literal>outbuf</>. It converts the long value according to the format
- mask to its textual representation.
+ The function receives the long value <literal>lng_val</>, the format
+ mask <literal>fmt</> and a pointer to the output buffer
+ <literal>outbuf</>. It converts the long value according to the format
+ mask to its textual representation.
</para>
<para>
- The format mask can be composed of the following format specifying
- characters:
+ The format mask can be composed of the following format specifying
+ characters:
<itemizedlist>
<listitem>
<para>
- <literal>*</literal> (asterisk) - if this position would be blank
- otherwise, fill it with an asterisk.
+ <literal>*</literal> (asterisk) - if this position would be blank
+ otherwise, fill it with an asterisk.
</para>
</listitem>
<listitem>
<para>
- <literal>&</literal> (ampersand) - if this position would be
- blank otherwise, fill it with a zero.
+ <literal>&</literal> (ampersand) - if this position would be
+ blank otherwise, fill it with a zero.
</para>
</listitem>
<listitem>
<para>
- <literal>#</literal> - turn leading zeroes into blanks.
+ <literal>#</literal> - turn leading zeroes into blanks.
</para>
</listitem>
<listitem>
<para>
- <literal><</literal> - left-justify the number in the string.
+ <literal><</literal> - left-justify the number in the string.
</para>
</listitem>
<listitem>
<para>
- <literal>,</literal> (comma) - group numbers of four or more digits
- into groups of three digits separated by a comma.
+ <literal>,</literal> (comma) - group numbers of four or more digits
+ into groups of three digits separated by a comma.
</para>
</listitem>
<listitem>
<para>
- <literal>.</literal> (period) - this character separates the
- whole-number part of the number from the fractional part.
+ <literal>.</literal> (period) - this character separates the
+ whole-number part of the number from the fractional part.
</para>
</listitem>
<listitem>
<para>
- <literal>-</literal> (minus) - the minus sign appears if the number
- is a negative value.
+ <literal>-</literal> (minus) - the minus sign appears if the number
+ is a negative value.
</para>
</listitem>
<listitem>
<para>
- <literal>+</literal> (plus) - the plus sign appears if the number is
- a positive value.
+ <literal>+</literal> (plus) - the plus sign appears if the number is
+ a positive value.
</para>
</listitem>
<listitem>
<para>
- <literal>(</literal> - this replaces the minus sign in front of the
- negative number. The minus sign will not appear.
+ <literal>(</literal> - this replaces the minus sign in front of the
+ negative number. The minus sign will not appear.
</para>
</listitem>
<listitem>
<para>
- <literal>)</literal> - this character replaces the minus and is
- printed behind the negative value.
+ <literal>)</literal> - this character replaces the minus and is
+ printed behind the negative value.
</para>
</listitem>
<listitem>
<para>
- <literal>$</literal> - the currency symbol.
+ <literal>$</literal> - the currency symbol.
</para>
</listitem>
- </itemizedlist>
+ </itemizedlist>
</para>
</listitem>
</varlistentry>
<synopsis>
void rupshift(char *str);
</synopsis>
- The function receives a pointer to the string and transforms every
- lower case character to upper case.
+ The function receives a pointer to the string and transforms every
+ lower case character to upper case.
</para>
</listitem>
</varlistentry>
<term><function>byleng</></term>
<listitem>
<para>
- Return the number of characters in a string without counting trailing
- blanks.
+ Return the number of characters in a string without counting trailing
+ blanks.
<synopsis>
int byleng(char *str, int len);
</synopsis>
- The function expects a fixed-length string as its first argument
- (<literal>str</>) and its length as its second argument
- (<literal>len</>). It returns the number of significant characters,
- that is the length of the string without trailing blanks.
+ The function expects a fixed-length string as its first argument
+ (<literal>str</>) and its length as its second argument
+ (<literal>len</>). It returns the number of significant characters,
+ that is the length of the string without trailing blanks.
</para>
</listitem>
</varlistentry>
<synopsis>
void ldchar(char *src, int len, char *dest);
</synopsis>
- The function receives the fixed-length string to copy
- (<literal>src</>), its length (<literal>len</>) and a pointer to the
- destination memory (<literal>dest</>). Note that you need to reserve at
- least <literal>len+1</> bytes for the string that <literal>dest</>
- points to. The function copies at most <literal>len</> bytes to the new
- location (less if the source string has trailing blanks) and adds the
- null-terminator.
+ The function receives the fixed-length string to copy
+ (<literal>src</>), its length (<literal>len</>) and a pointer to the
+ destination memory (<literal>dest</>). Note that you need to reserve at
+ least <literal>len+1</> bytes for the string that <literal>dest</>
+ points to. The function copies at most <literal>len</> bytes to the new
+ location (less if the source string has trailing blanks) and adds the
+ null-terminator.
</para>
</listitem>
</varlistentry>
<synopsis>
int rsetnull(int t, char *ptr);
</synopsis>
- The function receives an integer that indicates the type of the
- variable and a pointer to the variable itself that is casted to a C
- char* pointer.
+ The function receives an integer that indicates the type of the
+ variable and a pointer to the variable itself that is casted to a C
+ char* pointer.
</para>
<para>
The following types exist:
<itemizedlist>
<listitem>
<para>
- <literal>CCHARTYPE</literal> - For a variable of type <type>char</type> or <type>char*</type>
+ <literal>CCHARTYPE</literal> - For a variable of type <type>char</type> or <type>char*</type>
</para>
</listitem>
<listitem>
<para>
- <literal>CSHORTTYPE</literal> - For a variable of type <type>short int</type>
+ <literal>CSHORTTYPE</literal> - For a variable of type <type>short int</type>
</para>
</listitem>
<listitem>
<para>
- <literal>CINTTYPE</literal> - For a variable of type <type>int</type>
+ <literal>CINTTYPE</literal> - For a variable of type <type>int</type>
</para>
</listitem>
<listitem>
<para>
- <literal>CBOOLTYPE</literal> - For a variable of type <type>boolean</type>
+ <literal>CBOOLTYPE</literal> - For a variable of type <type>boolean</type>
</para>
</listitem>
<listitem>
<para>
- <literal>CFLOATTYPE</literal> - For a variable of type <type>float</type>
+ <literal>CFLOATTYPE</literal> - For a variable of type <type>float</type>
</para>
</listitem>
<listitem>
<para>
- <literal>CLONGTYPE</literal> - For a variable of type <type>long</type>
+ <literal>CLONGTYPE</literal> - For a variable of type <type>long</type>
</para>
</listitem>
<listitem>
<para>
- <literal>CDOUBLETYPE</literal> - For a variable of type <type>double</type>
+ <literal>CDOUBLETYPE</literal> - For a variable of type <type>double</type>
</para>
</listitem>
<listitem>
<para>
- <literal>CDECIMALTYPE</literal> - For a variable of type <type>decimal</type>
+ <literal>CDECIMALTYPE</literal> - For a variable of type <type>decimal</type>
</para>
</listitem>
<listitem>
<para>
- <literal>CDATETYPE</literal> - For a variable of type <type>date</type>
+ <literal>CDATETYPE</literal> - For a variable of type <type>date</type>
</para>
</listitem>
<listitem>
<para>
- <literal>CDTIMETYPE</literal> - For a variable of type <type>timestamp</type>
+ <literal>CDTIMETYPE</literal> - For a variable of type <type>timestamp</type>
</para>
</listitem>
</itemizedlist>
<synopsis>
int risnull(int t, char *ptr);
</synopsis>
- The function receives the type of the variable to test (<literal>t</>)
- as well a pointer to this variable (<literal>ptr</>). Note that the
- latter needs to be casted to a char*. See the function <xref
- linkend="rsetnull"> for a list of possible variable types.
+ The function receives the type of the variable to test (<literal>t</>)
+ as well a pointer to this variable (<literal>ptr</>). Note that the
+ latter needs to be casted to a char*. See the function <xref
+ linkend="rsetnull"> for a list of possible variable types.
</para>
<para>
Here is an example of how to use this function:
<term><literal>ECPG_INFORMIX_NUM_OVERFLOW</></term>
<listitem>
<para>
- Functions return this value if an overflow occurred in a
- calculation. Internally it is defined to -1200 (the <productname>Informix</productname>
- definition).
+ Functions return this value if an overflow occurred in a
+
calculation. Internally it is defined to -1200 (the <productname>Informix</productname>
+ definition).
</para>
</listitem>
</varlistentry>
<term><literal>ECPG_INFORMIX_NUM_UNDERFLOW</></term>
<listitem>
<para>
- Functions return this value if an underflow occurred in a calculation.
- Internally it is defined to -1201 (the <productname>Informix</productname> definition).
+ Functions return this value if an underflow occurred in a calculation.
+
Internally it is defined to -1201 (the <productname>Informix</productname> definition).
</para>
</listitem>
</varlistentry>
<term><literal>ECPG_INFORMIX_DIVIDE_ZERO</></term>
<listitem>
<para>
- Functions return this value if an attempt to divide by zero is
- observed. Internally it is defined to -1202 (the <productname>Informix</productname> definition).
+ Functions return this value if an attempt to divide by zero is
+
observed. Internally it is defined to -1202 (the <productname>Informix</productname> definition).
</para>
</listitem>
</varlistentry>
<term><literal>ECPG_INFORMIX_BAD_YEAR</></term>
<listitem>
<para>
- Functions return this value if a bad value for a year was found while
- parsing a date. Internally it is defined to -1204 (the <productname>Informix</productname>
- definition).
+ Functions return this value if a bad value for a year was found while
+
parsing a date. Internally it is defined to -1204 (the <productname>Informix</productname>
+ definition).
</para>
</listitem>
</varlistentry>
<term><literal>ECPG_INFORMIX_BAD_MONTH</></term>
<listitem>
<para>
- Functions return this value if a bad value for a month was found while
- parsing a date. Internally it is defined to -1205 (the <productname>Informix</productname>
- definition).
+ Functions return this value if a bad value for a month was found while
+
parsing a date. Internally it is defined to -1205 (the <productname>Informix</productname>
+ definition).
</para>
</listitem>
</varlistentry>
<term><literal>ECPG_INFORMIX_BAD_DAY</></term>
<listitem>
<para>
- Functions return this value if a bad value for a day was found while
- parsing a date. Internally it is defined to -1206 (the <productname>Informix</productname>
- definition).
+ Functions return this value if a bad value for a day was found while
+
parsing a date. Internally it is defined to -1206 (the <productname>Informix</productname>
+ definition).
</para>
</listitem>
</varlistentry>
<term><literal>ECPG_INFORMIX_ENOSHORTDATE</></term>
<listitem>
<para>
- Functions return this value if a parsing routine needs a short date
- representation but did not get the date string in the right length.
- Internally it is defined to -1209 (the <productname>Informix</productname> definition).
+ Functions return this value if a parsing routine needs a short date
+ representation but did not get the date string in the right length.
+
Internally it is defined to -1209 (the <productname>Informix</productname> definition).
</para>
</listitem>
</varlistentry>
<term><literal>ECPG_INFORMIX_DATE_CONVERT</></term>
<listitem>
<para>
- Functions return this value if Internally it is defined to -1210 (the
- <productname>Informix</productname> definition).
+ Functions return this value if Internally it is defined to -1210 (the
+
<productname>Informix</productname> definition).
</para>
</listitem>
</varlistentry>
<term><literal>ECPG_INFORMIX_OUT_OF_MEMORY</></term>
<listitem>
<para>
- Functions return this value if Internally it is defined to -1211 (the
- <productname>Informix</productname> definition).
+ Functions return this value if Internally it is defined to -1211 (the
+
<productname>Informix</productname> definition).
</para>
</listitem>
</varlistentry>
<term><literal>ECPG_INFORMIX_ENOTDMY</></term>
<listitem>
<para>
- Functions return this value if a parsing routine was supposed to get a
- format mask (like <literal>mmddyy</>) but not all fields were listed
- correctly. Internally it is defined to -1212 (the <productname>Informix</productname> definition).
+ Functions return this value if a parsing routine was supposed to get a
+ format mask (like <literal>mmddyy</>) but not all fields were listed
+
correctly. Internally it is defined to -1212 (the <productname>Informix</productname> definition).
</para>
</listitem>
</varlistentry>
<term><literal>ECPG_INFORMIX_BAD_NUMERIC</></term>
<listitem>
<para>
- Functions return this value either if a parsing routine cannot parse
- the textual representation for a numeric value because it contains
- errors or if a routine cannot complete a calculation involving numeric
- variables because at least one of the numeric variables is invalid.
- Internally it is defined to -1213 (the <productname>Informix</productname> definition).
+ Functions return this value either if a parsing routine cannot parse
+ the textual representation for a numeric value because it contains
+ errors or if a routine cannot complete a calculation involving numeric
+ variables because at least one of the numeric variables is invalid.
+
Internally it is defined to -1213 (the <productname>Informix</productname> definition).
</para>
</listitem>
</varlistentry>
<term><literal>ECPG_INFORMIX_BAD_EXPONENT</></term>
<listitem>
<para>
- Functions return this value if Internally it is defined to -1216 (the
- <productname>Informix</productname> definition).
+ Functions return this value if Internally it is defined to -1216 (the
+
<productname>Informix</productname> definition).
</para>
</listitem>
</varlistentry>
<term><literal>ECPG_INFORMIX_BAD_DATE</></term>
<listitem>
<para>
- Functions return this value if Internally it is defined to -1218 (the
- <productname>Informix</productname> definition).
+ Functions return this value if Internally it is defined to -1218 (the
+
<productname>Informix</productname> definition).
</para>
</listitem>
</varlistentry>
<term><literal>ECPG_INFORMIX_EXTRA_CHARS</></term>
<listitem>
<para>
- Functions return this value if Internally it is defined to -1264 (the
- <productname>Informix</productname> definition).
+ Functions return this value if Internally it is defined to -1264 (the
+
<productname>Informix</productname> definition).
</para>
</listitem>
</varlistentry>
-<!-- $PostgreSQL: pgsql/doc/src/sgml/sql.sgml,v 1.45 2007/02/01 19:10:24 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/sql.sgml,v 1.46 2007/02/16 03:50:29 momjian Exp $ -->
<chapter id="sql-intro">
<title>SQL</title>
<itemizedlist>
<listitem>
<para>
- SELECT (σ): extracts <firstterm>tuples</firstterm> from
- a relation that
- satisfy a given restriction. Let <parameter>R</parameter> be a
- table that contains an attribute
- <parameter>A</parameter>.
+ SELECT (σ): extracts <firstterm>tuples</firstterm> from
+ a relation that
+
satisfy a given restriction. Let <parameter>R</parameter> be a
+ table that contains an attribute
+
<parameter>A</parameter>.
σ<subscript>A=a</subscript>(R) = {t ∈ R ∣ t(A) = a}
- where <literal>t</literal> denotes a
- tuple of <parameter>R</parameter> and <literal>t(A)</literal>
- denotes the value of attribute <parameter>A</parameter> of
- tuple <literal>t</literal>.
+ where <literal>t</literal> denotes a
+
tuple of <parameter>R</parameter> and <literal>t(A)</literal>
+
denotes the value of attribute <parameter>A</parameter> of
+ tuple <literal>t</literal>.
</para>
</listitem>
<listitem>
<para>
- PROJECT (π): extracts specified
- <firstterm>attributes</firstterm> (columns) from a
- relation. Let <classname>R</classname> be a relation
- that contains an attribute <classname>X</classname>.
- π<subscript>X</subscript>(<classname>R</classname>) = {t(X) ∣ t ∈ <classname>R</classname>},
- where <literal>t</literal>(<classname>X</classname>) denotes the value of
- attribute <classname>X</classname> of tuple <literal>t</literal>.
+ PROJECT (π): extracts specified
+ <firstterm>attributes</firstterm> (columns) from a
+ relation. Let <classname>R</classname> be a relation
+ that contains an attribute <classname>X</classname>.
+ π<subscript>X</subscript>(<classname>R</classname>) = {t(X) ∣ t ∈ <classname>R</classname>},
+ where <literal>t</literal>(<classname>X</classname>) denotes the value of
+ attribute <classname>X</classname> of tuple <literal>t</literal>.
</para>
</listitem>
<listitem>
<para>
- PRODUCT (×): builds the Cartesian product of two
- relations. Let <classname>R</classname> be a table with arity
- <literal>k</literal><subscript>1</subscript> and let
- <classname>S</classname> be a table with
- arity <literal>k</literal><subscript>2</subscript>.
- <classname>R</classname> × <classname>S</classname>
- is the set of all
- <literal>k</literal><subscript>1</subscript>
- + <literal>k</literal><subscript>2</subscript>-tuples
- whose first <literal>k</literal><subscript>1</subscript>
- components form a tuple in <classname>R</classname> and whose last
- <literal>k</literal><subscript>2</subscript> components form a
- tuple in <classname>S</classname>.
+ PRODUCT (×): builds the Cartesian product of two
+ relations. Let <classname>R</classname> be a table with arity
+ <literal>k</literal><subscript>1</subscript> and let
+ <classname>S</classname> be a table with
+ arity <literal>k</literal><subscript>2</subscript>.
+ <classname>R</classname> × <classname>S</classname>
+ is the set of all
+ <literal>k</literal><subscript>1</subscript>
+ + <literal>k</literal><subscript>2</subscript>-tuples
+ whose first <literal>k</literal><subscript>1</subscript>
+ components form a tuple in <classname>R</classname> and whose last
+ <literal>k</literal><subscript>2</subscript> components form a
+ tuple in <classname>S</classname>.
</para>
</listitem>
<listitem>
<para>
- UNION (∪): builds the set-theoretic union of two
- tables. Given the tables <classname>R</classname> and
- <classname>S</classname> (both must have the same arity),
- the union <classname>R</classname> ∪ <classname>S</classname>
- is the set of tuples that are in <classname>R</classname>
- or <classname>S</classname> or both.
+ UNION (∪): builds the set-theoretic union of two
+ tables. Given the tables <classname>R</classname> and
+ <classname>S</classname> (both must have the same arity),
+ the union <classname>R</classname> ∪ <classname>S</classname>
+ is the set of tuples that are in <classname>R</classname>
+ or <classname>S</classname> or both.
</para>
</listitem>
<listitem>
<para>
- INTERSECT (∩): builds the set-theoretic intersection of two
- tables. Given the tables <classname>R</classname> and
- <classname>S</classname>,
- <classname>R</classname> ∩ <classname>S</classname> is the
- set of tuples
- that are in <classname>R</classname> and in
- <classname>S</classname>.
- We again require that <classname>R</classname> and
- <classname>S</classname> have the
- same arity.
+ INTERSECT (∩): builds the set-theoretic intersection of two
+ tables. Given the tables <classname>R</classname> and
+ <classname>S</classname>,
+ <classname>R</classname> ∩ <classname>S</classname> is the
+ set of tuples
+ that are in <classname>R</classname> and in
+ <classname>S</classname>.
+ We again require that <classname>R</classname> and
+ <classname>S</classname> have the
+ same arity.
</para>
</listitem>
<listitem>
<para>
- DIFFERENCE (− or ∖): builds the set difference of
- two tables. Let <classname>R</classname> and <classname>S</classname>
- again be two tables with the same
- arity. <classname>R</classname> - <classname>S</classname>
- is the set of tuples in <classname>R</classname> but not in
- <classname>S</classname>.
+ DIFFERENCE (− or ∖): builds the set difference of
+ two tables. Let <classname>R</classname> and <classname>S</classname>
+ again be two tables with the same
+ arity. <classname>R</classname> - <classname>S</classname>
+ is the set of tuples in <classname>R</classname> but not in
+ <classname>S</classname>.
</para>
</listitem>
<listitem>
<para>
- JOIN (∏): connects two tables by their common
- attributes. Let <classname>R</classname> be a table with the
- attributes <classname>A</classname>,<classname>B</classname>
- and <classname>C</classname> and
- let <classname>S</classname> be a table with the attributes
- <classname>C</classname>,<classname>D</classname>
- and <classname>E</classname>. There is one
- attribute common to both relations,
- the attribute <classname>C</classname>.
+ JOIN (∏): connects two tables by their common
+ attributes. Let <classname>R</classname> be a table with the
+ attributes <classname>A</classname>,<classname>B</classname>
+ and <classname>C</classname> and
+ let <classname>S</classname> be a table with the attributes
+ <classname>C</classname>,<classname>D</classname>
+ and <classname>E</classname>. There is one
+ attribute common to both relations,
+ the attribute <classname>C</classname>.
<!--
- <classname>R</classname> ∏ <classname>S</classname> =
- π<subscript><classname>R</classname>.<classname>A</classname>,<classname>R</classname>.<classname>B</classname>,<classname>R</classname>.<classname>C</classname>,<classname>S</classname>.<classname>D</classname>,<classname>S</classname>.<classname>E</classname></subscript>(σ<subscript><classname>R</classname>.<classname>C</classname>=<classname>S</classname>.<classname>C</classname></subscript>(<classname>R</classname> × <classname>S</classname>)).
+ <classname>R</classname> ∏ <classname>S</classname> =
+ π<subscript><classname>R</classname>.<classname>A</classname>,<classname>R</classname>.<classname>B</classname>,<classname>R</classname>.<classname>C</classname>,<classname>S</classname>.<classname>D</classname>,<classname>S</classname>.<classname>E</classname></subscript>(σ<subscript><classname>R</classname>.<classname>C</classname>=<classname>S</classname>.<classname>C</classname></subscript>(<classname>R</classname> × <classname>S</classname>)).
-->
- R ∏ S = π<subscript>R.A,R.B,R.C,S.D,S.E</subscript>(σ<subscript>R.C=S.C</subscript>(R × S)).
- What are we doing here? We first calculate the Cartesian
- product
- <classname>R</classname> × <classname>S</classname>.
- Then we select those tuples whose values for the common
- attribute <classname>C</classname> are equal
- (σ<subscript>R.C = S.C</subscript>).
- Now we have a table
- that contains the attribute <classname>C</classname>
- two times and we correct this by
- projecting out the duplicate column.
+ R ∏ S = π<subscript>R.A,R.B,R.C,S.D,S.E</subscript>(σ<subscript>R.C=S.C</subscript>(R × S)).
+ What are we doing here? We first calculate the Cartesian
+ product
+ <classname>R</classname> × <classname>S</classname>.
+ Then we select those tuples whose values for the common
+ attribute <classname>C</classname> are equal
+ (σ<subscript>R.C = S.C</subscript>).
+ Now we have a table
+ that contains the attribute <classname>C</classname>
+ two times and we correct this by
+ projecting out the duplicate column.
</para>
<example>
- <title id="join-example">An Inner Join</title>
+ <title id="join-example">An Inner Join</title>
- <para>
- Let's have a look at the tables that are produced by evaluating the steps
- necessary for a join.
- Let the following two tables be given:
+ Let's have a look at the tables that are produced by evaluating the steps
+ necessary for a join.
+ Let the following two tables be given:
- <programlisting>
R: S:
A | B | C C | D | E
---+---+--- ---+---+---
1 | 2 | 3 3 | a | b
4 | 5 | 6 6 | c | d
7 | 8 | 9
- </programlisting>
- </para>
+ </programlisting>
+ </para>
</example>
<para>
- First we calculate the Cartesian product
- <classname>R</classname> × <classname>S</classname> and
- get:
+ First we calculate the Cartesian product
+ <classname>R</classname> × <classname>S</classname> and
+ get:
- <programlisting>
R x S:
A | B | R.C | S.C | D | E
---+---+-----+-----+---+---
4 | 5 | 6 | 6 | c | d
7 | 8 | 9 | 3 | a | b
7 | 8 | 9 | 6 | c | d
- </programlisting>
+ </programlisting>
</para>
<para>
- After the selection
- σ<subscript>R.C=S.C</subscript>(R × S)
- we get:
+ After the selection
+ σ<subscript>R.C=S.C</subscript>(R × S)
+ we get:
- <programlisting>
A | B | R.C | S.C | D | E
---+---+-----+-----+---+---
1 | 2 | 3 | 3 | a | b
4 | 5 | 6 | 6 | c | d
- </programlisting>
+ </programlisting>
</para>
<para>
- To remove the duplicate column
- <classname>S</classname>.<classname>C</classname>
- we project it out by the following operation:
- π<subscript>R.A,R.B,R.C,S.D,S.E</subscript>(σ<subscript>R.C=S.C</subscript>(R × S))
- and get:
+ To remove the duplicate column
+ <classname>S</classname>.<classname>C</classname>
+ we project it out by the following operation:
+ π<subscript>R.A,R.B,R.C,S.D,S.E</subscript>(σ<subscript>R.C=S.C</subscript>(R × S))
+ and get:
- <programlisting>
A | B | C | D | E
---+---+---+---+---
1 | 2 | 3 | a | b
4 | 5 | 6 | c | d
- </programlisting>
+ </programlisting>
</para>
</listitem>
<listitem>
<para>
- DIVIDE (÷): Let <classname>R</classname> be a table
- with the attributes A, B, C, and D and let
- <classname>S</classname> be a table with the attributes
- C and D.
- Then we define the division as:
+ DIVIDE (÷): Let <classname>R</classname> be a table
+ with the attributes A, B, C, and D and let
+ <classname>S</classname> be a table with the attributes
+ C and D.
+ Then we define the division as:
- <programlisting>
R ÷ S = {t ∣ ∀ t<subscript>s</subscript> ∈ S ∃ t<subscript>r</subscript> ∈ R
- </programlisting>
+ </programlisting>
- such that
+ such that
t<subscript>r</subscript>(A,B)=t∧t<subscript>r</subscript>(C,D)=t<subscript>s</subscript>}
- where
- t<subscript>r</subscript>(x,y)
- denotes a
- tuple of table <classname>R</classname> that consists only of
- the components <literal>x</literal> and <literal>y</literal>.
- Note that the tuple <literal>t</literal> only consists of the
- components <classname>A</classname> and
- <classname>B</classname> of relation <classname>R</classname>.
+ where
+ t<subscript>r</subscript>(x,y)
+ denotes a
+ tuple of table <classname>R</classname> that consists only of
+ the components <literal>x</literal> and <literal>y</literal>.
+ Note that the tuple <literal>t</literal> only consists of the
+ components <classname>A</classname> and
+ <classname>B</classname> of relation <classname>R</classname>.
</para>
<para id="divide-example">
- Given the following tables
+ Given the following tables
- <programlisting>
R: S:
A | B | C | D C | D
---+---+---+--- ---+---
e | d | c | d
e | d | e | f
a | b | d | e
- </programlisting>
+ </programlisting>
- R ÷ S
- is derived as
+ R ÷ S
+ is derived as
- <programlisting>
A | B
---+---
a | b
e | d
- </programlisting>
+ </programlisting>
</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para>
- The <firstterm>Domain Relational Calculus</firstterm>
- (<acronym>DRC</acronym>), where variables
- stand for components (attributes) of the tuples.
+ The <firstterm>Domain Relational Calculus</firstterm>
+
(<acronym>DRC</acronym>), where variables
+ stand for components (attributes) of the tuples.
</para>
</listitem>
<listitem>
<para>
- The <firstterm>Tuple Relational Calculus</firstterm>
- (<acronym>TRC</acronym>), where variables stand for tuples.
+ The <firstterm>Tuple Relational Calculus</firstterm>
+
(<acronym>TRC</acronym>), where variables stand for tuples.
</para>
</listitem>
</itemizedlist>
<example>
<title id="simple-query">Simple Query with Qualification</title>
<para>
- To retrieve all tuples from table PART where the attribute PRICE is
- greater than 10 we formulate the following query:
+ To retrieve all tuples from table PART where the attribute PRICE is
+ greater than 10 we formulate the following query:
- <programlisting>
SELECT * FROM PART
WHERE PRICE > 10;
- </programlisting>
+ </programlisting>
- and get the table:
+ and get the table:
- <programlisting>
PNO | PNAME | PRICE
-----+---------+--------
3 | Bolt | 15
4 | Cam | 25
- </programlisting>
+ </programlisting>
</para>
<para>
- Using <quote>*</quote> in the <command>SELECT</command> statement
- will deliver all attributes from the table. If we want to retrieve
- only the attributes PNAME and PRICE from table PART we use the
- statement:
+ Using <quote>*</quote> in the <command>SELECT</command> statement
+ will deliver all attributes from the table. If we want to retrieve
+ only the attributes PNAME and PRICE from table PART we use the
+ statement:
- <programlisting>
SELECT PNAME, PRICE
FROM PART
WHERE PRICE > 10;
- </programlisting>
+ </programlisting>
- In this case the result is:
+ In this case the result is:
- <programlisting>
PNAME | PRICE
--------+--------
Bolt | 15
Cam | 25
- </programlisting>
+ </programlisting>
- Note that the <acronym>SQL</acronym> <command>SELECT</command>
- corresponds to the <quote>projection</quote> in relational algebra
- not to the <quote>selection</quote> (see <xref linkend="rel-alg"
- endterm="rel-alg"> for more details).
+
Note that the <acronym>SQL</acronym> <command>SELECT</command>
+ corresponds to the <quote>projection</quote> in relational algebra
+ not to the <quote>selection</quote> (see <xref linkend="rel-alg"
+ endterm="rel-alg"> for more details).
</para>
<para>
- The qualifications in the WHERE clause can also be logically connected
- using the keywords OR, AND, and NOT:
+ The qualifications in the WHERE clause can also be logically connected
+ using the keywords OR, AND, and NOT:
- <programlisting>
SELECT PNAME, PRICE
FROM PART
WHERE PNAME = 'Bolt' AND
(PRICE = 0 OR PRICE <= 15);
- </programlisting>
+ </programlisting>
- will lead to the result:
+ will lead to the result:
- <programlisting>
PNAME | PRICE
--------+--------
Bolt | 15
- </programlisting>
+ </programlisting>
</para>
<para>
- Arithmetic operations can be used in the target list and in the WHERE
- clause. For example if we want to know how much it would cost if we
- take two pieces of a part we could use the following query:
+ Arithmetic operations can be used in the target list and in the WHERE
+ clause. For example if we want to know how much it would cost if we
+ take two pieces of a part we could use the following query:
- <programlisting>
SELECT PNAME, PRICE * 2 AS DOUBLE
FROM PART
WHERE PRICE * 2 < 50;
- </programlisting>
+ </programlisting>
- and we get:
+ and we get:
- <programlisting>
PNAME | DOUBLE
--------+---------
Screw | 20
Nut | 16
Bolt | 30
- </programlisting>
-
- Note that the word DOUBLE after the keyword AS is the new title of the
- second column. This technique can be used for every element of the
- target list to assign a new title to the resulting
- column. This new title
- is often referred to as alias. The alias cannot be used throughout the
- rest of the query.
+ </programlisting>
+
+ Note that the word DOUBLE after the keyword AS is the new title of the
+ second column. This technique can be used for every element of the
+ target list to assign a new title to the resulting
+ column. This new title
+ is often referred to as alias. The alias cannot be used throughout the
+ rest of the query.
</para>
</example>
</para>
columns but S.SNAME and P.PNAME.
</para>
- Another way to perform joins is to use the SQL JOIN syntax as follows:
+ <para>
+ Another way to perform joins is to use the SQL JOIN syntax as follows:
+ <programlisting>
select sname, pname from supplier
- JOIN sells USING (sno)
- JOIN part USING (pno);
- </programlisting>
- giving again:
+ JOIN sells USING (sno)
+ JOIN part USING (pno);
+ </programlisting>
+ giving again:
+ <programlisting>
sname | pname
-------+-------
Smith | Screw
Jones | Cam
Blake | Cam
(8 rows)
- </programlisting>
- </para>
-
- A joined table, created using JOIN syntax, is a table reference list
- item that occurs in a FROM clause and before any WHERE, GROUP BY,
- or HAVING clause. Other table references, including table names or
- other JOIN clauses, can be included in the FROM clause if separated
- by commas. JOINed tables are logically like any other
- table listed in the FROM clause.
- </para>
-
- SQL JOINs come in two main types, CROSS JOINs (unqualified joins)
- and <firstterm>qualified JOINs</>. Qualified joins can be further
- subdivided based on the way in which the <firstterm>join condition</>
- is specified (ON, USING, or NATURAL) and the way in which it is
- applied (INNER or OUTER join).
- </para>
+ </programlisting>
+ </para>
+
+ <para>
+ A joined table, created using JOIN syntax, is a table reference list
+ item that occurs in a FROM clause and before any WHERE, GROUP BY,
+ or HAVING clause. Other table references, including table names or
+ other JOIN clauses, can be included in the FROM clause if separated
+ by commas. JOINed tables are logically like any other
+ table listed in the FROM clause.
+ </para>
+
+ <para>
+ SQL JOINs come in two main types, CROSS JOINs (unqualified joins)
+ and <firstterm>qualified JOINs</>. Qualified joins can be further
+ subdivided based on the way in which the <firstterm>join condition</>
+ is specified (ON, USING, or NATURAL) and the way in which it is
+ applied (INNER or OUTER join).
+ </para>
<variablelist>
<title>Join Types</title>
<varlistentry>
<term>CROSS JOIN</term>
- <listitem>
- <cmdsynopsis>
- <arg choice="req"> <replaceable class="parameter">T1</replaceable> </arg>
- <command> CROSS JOIN </command>
- <arg choice="req"> <replaceable class="parameter">T2</replaceable> </arg>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="req"> <replaceable class="parameter">T1</replaceable> </arg>
+ <command> CROSS JOIN </command>
+ <arg choice="req"> <replaceable class="parameter">T2</replaceable> </arg>
+ </cmdsynopsis>
+
+ <para>
+ A cross join takes two tables T1 and T2 having N and M rows
+ respectively, and returns a joined table containing all
+ N*M possible joined rows. For each row R1 of T1, each row
+ R2 of T2 is joined with R1 to yield a joined table row JR
+ consisting of all fields in R1 and R2. A CROSS JOIN is
+ equivalent to an INNER JOIN ON TRUE.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Qualified JOINs</term>
+ <listitem>
+
+ <cmdsynopsis>
+ <arg choice="req"> <replaceable class="parameter">T1</replaceable> </arg>
+ <arg choice="opt"> NATURAL </arg>
+ <group choice="opt">
+ <arg choice="opt"> INNER </arg>
+ <arg>
+ <group choice="req">
+ <arg choice="plain"> LEFT </arg>
+ <arg choice="plain"> RIGHT </arg>
+ <arg choice="plain"> FULL </arg>
+ </group>
+ <arg choice="opt"> OUTER </arg>
+ </arg>
+ </group>
+ <command> JOIN </command>
+ <arg choice="req"> <replaceable class="parameter">T2</replaceable> </arg>
+ <group choice="req">
+ <arg> ON <replaceable>search condition</replaceable></arg>
+ <arg> USING ( <replaceable>join column list</replaceable> ) </arg>
+ </group>
</cmdsynopsis>
- <para>
- A cross join takes two tables T1 and T2 having N and M rows
- respectively, and returns a joined table containing all
- N*M possible joined rows. For each row R1 of T1, each row
- R2 of T2 is joined with R1 to yield a joined table row JR
- consisting of all fields in R1 and R2. A CROSS JOIN is
- equivalent to an INNER JOIN ON TRUE.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Qualified JOINs</term>
- <listitem>
-
- <cmdsynopsis>
- <arg choice="req"> <replaceable class="parameter">T1</replaceable> </arg>
- <arg choice="opt"> NATURAL </arg>
- <group choice="opt">
- <arg choice="opt"> INNER </arg>
- <arg>
- <group choice="req">
- <arg choice="plain"> LEFT </arg>
- <arg choice="plain"> RIGHT </arg>
- <arg choice="plain"> FULL </arg>
- </group>
- <arg choice="opt"> OUTER </arg>
- </arg>
- </group>
- <command> JOIN </command>
- <arg choice="req"> <replaceable class="parameter">T2</replaceable> </arg>
- <group choice="req">
- <arg> ON <replaceable>search condition</replaceable></arg>
- <arg> USING ( <replaceable>join column list</replaceable> ) </arg>
- </group>
- </cmdsynopsis>
-
- <para>
- A qualified JOIN must specify its join condition
- by providing one (and only one) of NATURAL, ON, or
- USING. The ON clause
- takes a <replaceable>search condition</replaceable>,
- which is the same as in a WHERE clause. The USING
- clause takes a comma-separated list of column names,
- which the joined tables must have in common, and joins
- the tables on equality of those columns. NATURAL is
- shorthand for a USING clause that lists all the common
- column names of the two tables. A side-effect of both
- USING and NATURAL is that only one copy of each joined
- column is emitted into the result table (compare the
- relational-algebra definition of JOIN, shown earlier).
- </para>
-
- <!-- begin join semantics -->
- <variablelist>
- <varlistentry>
- <term>
- <cmdsynopsis>
- <arg> INNER </arg>
- <command> JOIN </command>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- For each row R1 of T1, the joined table has a row for each row
- in T2 that satisfies the join condition with R1.
- </para>
- <tip>
- <para>
- The words INNER and OUTER are optional for all JOINs.
- INNER is the default. LEFT, RIGHT, and FULL imply an
- OUTER JOIN.
- </para>
- </tip>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <cmdsynopsis>
- <arg choice="plain"> LEFT </arg>
- <arg> OUTER </arg>
- <command> JOIN </command>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
+ <para>
+ A qualified JOIN must specify its join condition
+ by providing one (and only one) of NATURAL, ON, or
+ USING. The ON clause
+ takes a <replaceable>search condition</replaceable>,
+ which is the same as in a WHERE clause. The USING
+ clause takes a comma-separated list of column names,
+ which the joined tables must have in common, and joins
+ the tables on equality of those columns. NATURAL is
+ shorthand for a USING clause that lists all the common
+ column names of the two tables. A side-effect of both
+ USING and NATURAL is that only one copy of each joined
+ column is emitted into the result table (compare the
+ relational-algebra definition of JOIN, shown earlier).
+ </para>
+
+ <!-- begin join semantics -->
+ <variablelist>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <arg> INNER </arg>
+ <command> JOIN </command>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ For each row R1 of T1, the joined table has a row for each row
+ in T2 that satisfies the join condition with R1.
+ </para>
+ <tip>
+ <para>
+ The words INNER and OUTER are optional for all JOINs.
+ INNER is the default. LEFT, RIGHT, and FULL imply an
+ OUTER JOIN.
+ </para>
+ </tip>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <arg choice="plain"> LEFT </arg>
+ <arg> OUTER </arg>
+ <command> JOIN </command>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
First, an INNER JOIN is performed.
Then, for each row in T1 that does not satisfy the join
- condition with any row in T2, an additional joined row is
- returned with null fields in the columns from T2.
- </para>
- <tip>
- The joined table unconditionally has a row for each row in T1.
- </para>
- </tip>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <cmdsynopsis>
-
<arg choice="plain"> RIGHT </arg>
- <command> JOIN </command>
- </cmdsynopsis>
- </term>
- <listitem>
+ condition with any row in T2, an additional joined row is
+ returned with null fields in the columns from T2.
+ </para>
+ <tip>
+ <para>
+ The joined table unconditionally has a row for each row in T1.
+ </para>
+ </tip>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <arg choice="plain"> RIGHT </arg>
+ <arg> OUTER </arg>
+ <command> JOIN </command>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
First, an INNER JOIN is performed.
Then, for each row in T2 that does not satisfy the join
- condition with any row in T1, an additional joined row is
- returned with null fields in the columns from T1.
- </para>
- <tip>
- The joined table unconditionally has a row for each row in T2.
- </para>
- </tip>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <cmdsynopsis>
-
<arg choice="plain"> FULL </arg>
- <command> JOIN </command>
- </cmdsynopsis>
- </term>
- <listitem>
+ condition with any row in T1, an additional joined row is
+ returned with null fields in the columns from T1.
+ </para>
+ <tip>
+ <para>
+ The joined table unconditionally has a row for each row in T2.
+ </para>
+ </tip>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <arg choice="plain"> FULL </arg>
+ <arg> OUTER </arg>
+ <command> JOIN </command>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
First, an INNER JOIN is performed.
Then, for each row in T1 that does not satisfy the join
- condition with any row in T2, an additional joined row is
- returned with null fields in the columns from T2.
+ condition with any row in T2, an additional joined row is
+ returned with null fields in the columns from T2.
Also, for each row in T2 that does not satisfy the join
- condition with any row in T1, an additional joined row is
- returned with null fields in the columns from T1.
- </para>
- <tip>
- The joined table unconditionally has a row for every row of T1
- and a row for every row of T2.
- </para>
- </tip>
- </listitem>
- </varlistentry>
- </variablelist>
- <!-- end join semantics -->
-
- </listitem>
+ condition with any row in T1, an additional joined row is
+ returned with null fields in the columns from T1.
+ </para>
+ <tip>
+ <para>
+ The joined table unconditionally has a row for every row of T1
+ and a row for every row of T2.
+ </para>
+ </tip>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <!-- end join semantics -->
+
+ </listitem>
</varlistentry>
- </variablelist>
+ </variablelist>
- JOINs of all types can be chained together or nested where either or both of
- <replaceable class="parameter">T1</replaceable> and
- <replaceable class="parameter">T2</replaceable> can be JOINed tables.
- Parenthesis can be used around JOIN clauses to control the order
- of JOINs which are otherwise processed left to right.
- </para>
+ <para>
+ JOINs of all types can be chained together or nested where either or both of
+ <replaceable class="parameter">T1</replaceable> and
+ <replaceable class="parameter">T2</replaceable> can be JOINed tables.
+ Parenthesis can be used around JOIN clauses to control the order
+ of JOINs which are otherwise processed left to right.
+ </para>
</sect3>
<title id="aggregates-example">Aggregates</title>
<para>
- If we want to know the average cost of all parts in table PART we use
- the following query:
+ If we want to know the average cost of all parts in table PART we use
+ the following query:
- <programlisting>
SELECT AVG(PRICE) AS AVG_PRICE
FROM PART;
- </programlisting>
+ </programlisting>
</para>
<para>
- The result is:
+ The result is:
- <programlisting>
AVG_PRICE
-----------
14.5
- </programlisting>
+ </programlisting>
</para>
<para>
- If we want to know how many parts are defined in table PART we use
- the statement:
+ If we want to know how many parts are defined in table PART we use
+ the statement:
- <programlisting>
SELECT COUNT(PNO)
FROM PART;
- </programlisting>
+ </programlisting>
- and get:
+ and get:
- <programlisting>
COUNT
-------
4
- </programlisting>
+ </programlisting>
</para>
</example>
<example>
<title id="aggregates-groupby">Aggregates</title>
<para>
- If we want to know how many parts are sold by every supplier we
- formulate the query:
+ If we want to know how many parts are sold by every supplier we
+ formulate the query:
- <programlisting>
SELECT S.SNO, S.SNAME, COUNT(SE.PNO)
FROM SUPPLIER S, SELLS SE
WHERE S.SNO = SE.SNO
GROUP BY S.SNO, S.SNAME;
- </programlisting>
+ </programlisting>
- and get:
+ and get:
- <programlisting>
SNO | SNAME | COUNT
-----+-------+-------
1 | Smith | 2
2 | Jones | 1
3 | Adams | 2
4 | Blake | 3
- </programlisting>
+ </programlisting>
</para>
<para>
- Now let's have a look of what is happening here.
- First the join of the
- tables SUPPLIER and SELLS is derived:
+ Now let's have a look of what is happening here.
+ First the join of the
+ tables SUPPLIER and SELLS is derived:
- <programlisting>
S.SNO | S.SNAME | SE.PNO
-------+---------+--------
1 | Smith | 1
4 | Blake | 2
4 | Blake | 3
4 | Blake | 4
- </programlisting>
+ </programlisting>
</para>
<para>
- Next we partition the tuples into groups by putting all tuples
- together that agree on both attributes S.SNO and S.SNAME:
+ Next we partition the tuples into groups by putting all tuples
+ together that agree on both attributes S.SNO and S.SNAME:
- <programlisting>
S.SNO | S.SNAME | SE.PNO
-------+---------+--------
1 | Smith | 1
4 | Blake | 2
| 3
| 4
- </programlisting>
+ </programlisting>
</para>
<para>
- In our example we got four groups and now we can apply the aggregate
- function COUNT to every group leading to the final result of the query
- given above.
+ In our example we got four groups and now we can apply the aggregate
+ function COUNT to every group leading to the final result of the query
+ given above.
</para>
</example>
</para>
<title id="having-example">Having</title>
<para>
- If we want only those suppliers selling more than one part we use the
- query:
+ If we want only those suppliers selling more than one part we use the
+ query:
- <programlisting>
SELECT S.SNO, S.SNAME, COUNT(SE.PNO)
FROM SUPPLIER S, SELLS SE
WHERE S.SNO = SE.SNO
GROUP BY S.SNO, S.SNAME
HAVING COUNT(SE.PNO) > 1;
- </programlisting>
+ </programlisting>
- and get:
+ and get:
- <programlisting>
SNO | SNAME | COUNT
-----+-------+-------
1 | Smith | 2
3 | Adams | 2
4 | Blake | 3
- </programlisting>
+ </programlisting>
</para>
</example>
</para>
<title id="subselect-example">Subselect</title>
<para>
- If we want to know all parts having a greater price than the part
- named 'Screw' we use the query:
+ If we want to know all parts having a greater price than the part
+ named 'Screw' we use the query:
- <programlisting>
SELECT *
FROM PART
WHERE PRICE > (SELECT PRICE FROM PART
WHERE PNAME='Screw');
- </programlisting>
+ </programlisting>
</para>
<para>
- The result is:
+ The result is:
- <programlisting>
PNO | PNAME | PRICE
-----+---------+--------
3 | Bolt | 15
4 | Cam | 25
- </programlisting>
+ </programlisting>
</para>
<para>
- When we look at the above query we can see the keyword
- <command>SELECT</command> two times. The first one at the
- beginning of the query - we will refer to it as outer
- <command>SELECT</command> - and the one in the WHERE clause which
- begins a nested query - we will refer to it as inner
- <command>SELECT</command>. For every tuple of the outer
- <command>SELECT</command> the inner <command>SELECT</command> has
- to be evaluated. After every evaluation we know the price of the
- tuple named 'Screw' and we can check if the price of the actual
- tuple is greater. (Actually, in this example the inner query need
- only be evaluated once, since it does not depend on the state of
- the outer query.)
+ When we look at the above query we can see the keyword
+ <command>SELECT</command> two times. The first one at the
+ beginning of the query - we will refer to it as outer
+ <command>SELECT</command> - and the one in the WHERE clause which
+ begins a nested query - we will refer to it as inner
+ <command>SELECT</command>. For every tuple of the outer
+ <command>SELECT</command> the inner <command>SELECT</command> has
+ to be evaluated. After every evaluation we know the price of the
+ tuple named 'Screw' and we can check if the price of the actual
+ tuple is greater. (Actually, in this example the inner query need
+ only be evaluated once, since it does not depend on the state of
+ the outer query.)
</para>
<para>
- If we want to know all suppliers that do not sell any part
- (e.g. to be able to remove these suppliers from the database) we use:
+ If we want to know all suppliers that do not sell any part
+ (e.g. to be able to remove these suppliers from the database) we use:
- <programlisting>
SELECT *
FROM SUPPLIER S
WHERE NOT EXISTS
(SELECT * FROM SELLS SE
WHERE SE.SNO = S.SNO);
- </programlisting>
+ </programlisting>
</para>
<para>
- In our example the result will be empty because every supplier
- sells at least one part. Note that we use S.SNO from the outer
- <command>SELECT</command> within the WHERE clause of the inner
- <command>SELECT</command>. Here the subquery must be evaluated
- afresh for each tuple from the outer query, i.e. the value for
- S.SNO is always taken from the current tuple of the outer
- <command>SELECT</command>.
+ In our example the result will be empty because every supplier
+ sells at least one part. Note that we use S.SNO from the outer
+ <command>SELECT</command> within the WHERE clause of the inner
+ <command>SELECT</command>. Here the subquery must be evaluated
+ afresh for each tuple from the outer query, i.e. the value for
+ S.SNO is always taken from the current tuple of the outer
+ <command>SELECT</command>.
</para>
</example>
</para>
<para>
If we want to know the highest average part price among all our
- suppliers, we cannot write MAX(AVG(PRICE)), but we can write:
+ suppliers, we cannot write MAX(AVG(PRICE)), but we can write:
- <programlisting>
SELECT MAX(subtable.avgprice)
FROM (SELECT AVG(P.PRICE) AS avgprice
FROM SUPPLIER S, PART P, SELLS SE
WHERE S.SNO = SE.SNO AND
P.PNO = SE.PNO
GROUP BY S.SNO) subtable;
- </programlisting>
+ </programlisting>
- The subquery returns one row per supplier (because of its GROUP BY)
- and then we aggregate over those rows in the outer query.
+ The subquery returns one row per supplier (because of its GROUP BY)
+ and then we aggregate over those rows in the outer query.
</para>
</example>
</para>
<title id="union-example">Union, Intersect, Except</title>
<para>
- The following query is an example for UNION:
+ The following query is an example for UNION:
- <programlisting>
SELECT S.SNO, S.SNAME, S.CITY
FROM SUPPLIER S
WHERE S.SNAME = 'Jones'
SELECT S.SNO, S.SNAME, S.CITY
FROM SUPPLIER S
WHERE S.SNAME = 'Adams';
- </programlisting>
+ </programlisting>
gives the result:
- <programlisting>
SNO | SNAME | CITY
-----+-------+--------
2 | Jones | Paris
3 | Adams | Vienna
- </programlisting>
+ </programlisting>
</para>
<para>
- Here is an example for INTERSECT:
+ Here is an example for INTERSECT:
- <programlisting>
SELECT S.SNO, S.SNAME, S.CITY
FROM SUPPLIER S
WHERE S.SNO > 1
SELECT S.SNO, S.SNAME, S.CITY
FROM SUPPLIER S
WHERE S.SNO < 3;
- </programlisting>
+ </programlisting>
- gives the result:
+ gives the result:
- <programlisting>
SNO | SNAME | CITY
-----+-------+--------
2 | Jones | Paris
- </programlisting>
+ </programlisting>
- The only tuple returned by both parts of the query is the one having SNO=2.
+ The only tuple returned by both parts of the query is the one having SNO=2.
</para>
<para>
- Finally an example for EXCEPT:
+ Finally an example for EXCEPT:
- <programlisting>
SELECT S.SNO, S.SNAME, S.CITY
FROM SUPPLIER S
WHERE S.SNO > 1
SELECT S.SNO, S.SNAME, S.CITY
FROM SUPPLIER S
WHERE S.SNO > 3;
- </programlisting>
+ </programlisting>
- gives the result:
+ gives the result:
- <programlisting>
SNO | SNAME | CITY
-----+-------+--------
2 | Jones | Paris
3 | Adams | Vienna
- </programlisting>
+ </programlisting>
</para>
</example>
</para>
<title id="table-create">Table Creation</title>
<para>
- To create the tables defined in
- <xref linkend="supplier-fig" endterm="supplier-fig"> the
- following <acronym>SQL</acronym> statements are used:
+ To create the tables defined in
+ <xref linkend="supplier-fig" endterm="supplier-fig"> the
+
following <acronym>SQL</acronym> statements are used:
- <programlisting>
CREATE TABLE SUPPLIER
(SNO INTEGER,
SNAME VARCHAR(20),
CREATE TABLE SELLS
(SNO INTEGER,
PNO INTEGER);
- </programlisting>
+ </programlisting>
</para>
</example>
</para>
<itemizedlist>
<listitem>
- <para>
- INTEGER: signed fullword binary integer (31 bits precision).
- </para>
+ INTEGER: signed fullword binary integer (31 bits precision).
+ </para>
</listitem>
<listitem>
- <para>
- SMALLINT: signed halfword binary integer (15 bits precision).
- </para>
+ SMALLINT: signed halfword binary integer (15 bits precision).
+ </para>
</listitem>
<listitem>
- <para>
- DECIMAL (<replaceable class="parameter">p</replaceable>[,<replaceable class="parameter">q</replaceable>]):
- signed packed decimal number of up to
- <replaceable class="parameter">p</replaceable>
- digits, with
- <replaceable class="parameter">q</replaceable>
- digits to the right of the decimal point.
- If <replaceable class="parameter">q</replaceable>
- is omitted it is assumed to be 0.
- </para>
+ DECIMAL (<replaceable class="parameter">p</replaceable>[,<replaceable class="parameter">q</replaceable>]):
+ signed packed decimal number of up to
+ <replaceable class="parameter">p</replaceable>
+ digits, with
+ <replaceable class="parameter">q</replaceable>
+ digits to the right of the decimal point.
+ If <replaceable class="parameter">q</replaceable>
+ is omitted it is assumed to be 0.
+ </para>
</listitem>
<listitem>
- <para>
- FLOAT: signed doubleword floating point number.
- </para>
+ FLOAT: signed doubleword floating point number.
+ </para>
</listitem>
<listitem>
- <para>
- VARCHAR(<replaceable class="parameter">n</replaceable>):
- varying length character string of maximum length
- <replaceable class="parameter">n</replaceable>.
- </para>
+ VARCHAR(<replaceable class="parameter">n</replaceable>):
+ varying length character string of maximum length
+ <replaceable class="parameter">n</replaceable>.
+ </para>
</listitem>
<listitem>
- <para>
- CHAR(<replaceable class="parameter">n</replaceable>):
- fixed length character string of length
- <replaceable class="parameter">n</replaceable>.
- </para>
+ CHAR(<replaceable class="parameter">n</replaceable>):
+ fixed length character string of length
+ <replaceable class="parameter">n</replaceable>.
+ </para>
</listitem>
</itemizedlist>
<title id="index-create">Create Index</title>
<para>
- To create an index named I on attribute SNAME of relation SUPPLIER
- we use the following statement:
+ To create an index named I on attribute SNAME of relation SUPPLIER
+ we use the following statement:
<programlisting>
CREATE INDEX I ON SUPPLIER (SNAME);
</para>
<para>
- The created index is maintained automatically, i.e. whenever a new
- tuple is inserted into the relation SUPPLIER the index I is
- adapted. Note that the only changes a user can perceive when an
- index is present are increased speed for <command>SELECT</command>
- and decreases in speed of updates.
+ The created index is maintained automatically, i.e. whenever a new
+ tuple is inserted into the relation SUPPLIER the index I is
+ adapted. Note that the only changes a user can perceive when an
+ index is present are increased speed for <command>SELECT</command>
+ and decreases in speed of updates.
</para>
</example>
</para>
<itemizedlist>
<listitem>
<para>
- There are queries that cannot be formulated using pure <acronym>SQL</acronym>
- (i.e. recursive queries). To be able to perform such queries we need a
- host language with a greater expressive power than
- <acronym>SQL</acronym>.
+
There are queries that cannot be formulated using pure <acronym>SQL</acronym>
+ (i.e. recursive queries). To be able to perform such queries we need a
+ host language with a greater expressive power than
+
<acronym>SQL</acronym>.
</para>
</listitem>
<listitem>
<para>
- We simply want to access a database from some application that
- is written in the host language (e.g. a ticket reservation system
- with a graphical user interface is written in C and the information
- about which tickets are still left is stored in a database that can be
- accessed using embedded <acronym>SQL</acronym>).
+ We simply want to access a database from some application that
+ is written in the host language (e.g. a ticket reservation system
+ with a graphical user interface is written in C and the information
+ about which tickets are still left is stored in a database that can be
+
accessed using embedded <acronym>SQL</acronym>).
</para>
</listitem>
</itemizedlist>
projects / postgresql / commitdiff