1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.6. pgtypes Library</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-dynamic.html" title="34.5. Dynamic SQL" /><link rel="next" href="ecpg-descriptors.html" title="34.7. Using Descriptor Areas" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.6. pgtypes Library</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-dynamic.html" title="34.5. Dynamic SQL">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg.html" title="Chapter 34. ECPG — Embedded SQL in C">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-descriptors.html" title="34.7. Using Descriptor Areas">Next</a></td></tr></table><hr /></div><div class="sect1" id="ECPG-PGTYPES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.6. pgtypes Library <a href="#ECPG-PGTYPES" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-CSTRINGS">34.6.1. Character Strings</a></span></dt><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-NUMERIC">34.6.2. The numeric Type</a></span></dt><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-DATE">34.6.3. The date Type</a></span></dt><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-TIMESTAMP">34.6.4. The timestamp Type</a></span></dt><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-INTERVAL">34.6.5. The interval Type</a></span></dt><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-DECIMAL">34.6.6. The decimal Type</a></span></dt><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-ERRNO">34.6.7. errno Values of pgtypeslib</a></span></dt><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-CONSTANTS">34.6.8. Special Constants of pgtypeslib</a></span></dt></dl></div><p>
3 The pgtypes library maps <span class="productname">PostgreSQL</span> database
4 types to C equivalents that can be used in C programs. It also offers
5 functions to do basic calculations with those types within C, i.e., without
6 the help of the <span class="productname">PostgreSQL</span> server. See the
8 </p><pre class="programlisting">
9 EXEC SQL BEGIN DECLARE SECTION;
14 EXEC SQL END DECLARE SECTION;
16 PGTYPESdate_today(&date1);
17 EXEC SQL SELECT started, duration INTO :ts1, :iv1 FROM datetbl WHERE d=:date1;
18 PGTYPEStimestamp_add_interval(&ts1, &iv1, &tsout);
19 out = PGTYPEStimestamp_to_asc(&tsout);
20 printf("Started + duration: %s\n", out);
21 PGTYPESchar_free(out);
24 </p><div class="sect2" id="ECPG-PGTYPES-CSTRINGS"><div class="titlepage"><div><div><h3 class="title">34.6.1. Character Strings <a href="#ECPG-PGTYPES-CSTRINGS" class="id_link">#</a></h3></div></div></div><p>
25 Some functions such as <code class="function">PGTYPESnumeric_to_asc</code> return
26 a pointer to a freshly allocated character string. These results should be
27 freed with <code class="function">PGTYPESchar_free</code> instead of
28 <code class="function">free</code>. (This is important only on Windows, where
29 memory allocation and release sometimes need to be done by the same
31 </p></div><div class="sect2" id="ECPG-PGTYPES-NUMERIC"><div class="titlepage"><div><div><h3 class="title">34.6.2. The numeric Type <a href="#ECPG-PGTYPES-NUMERIC" class="id_link">#</a></h3></div></div></div><p>
32 The numeric type offers to do calculations with arbitrary precision. See
33 <a class="xref" href="datatype-numeric.html" title="8.1. Numeric Types">Section 8.1</a> for the equivalent type in the
34 <span class="productname">PostgreSQL</span> server. Because of the arbitrary precision this
35 variable needs to be able to expand and shrink dynamically. That's why you
36 can only create numeric variables on the heap, by means of the
37 <code class="function">PGTYPESnumeric_new</code> and <code class="function">PGTYPESnumeric_free</code>
38 functions. The decimal type, which is similar but limited in precision,
39 can be created on the stack as well as on the heap.
41 The following functions can be used to work with the numeric type:
42 </p><div class="variablelist"><dl class="variablelist"><dt id="ECPG-PGTYPES-NUMERIC-NEW"><span class="term"><code class="function">PGTYPESnumeric_new</code></span> <a href="#ECPG-PGTYPES-NUMERIC-NEW" class="id_link">#</a></dt><dd><p>
43 Request a pointer to a newly allocated numeric variable.
44 </p><pre class="synopsis">
45 numeric *PGTYPESnumeric_new(void);
47 </p></dd><dt id="ECPG-PGTYPES-NUMERIC-FREE"><span class="term"><code class="function">PGTYPESnumeric_free</code></span> <a href="#ECPG-PGTYPES-NUMERIC-FREE" class="id_link">#</a></dt><dd><p>
48 Free a numeric type, release all of its memory.
49 </p><pre class="synopsis">
50 void PGTYPESnumeric_free(numeric *var);
52 </p></dd><dt id="ECPG-PGTYPES-NUMERIC-FROM-ASC"><span class="term"><code class="function">PGTYPESnumeric_from_asc</code></span> <a href="#ECPG-PGTYPES-NUMERIC-FROM-ASC" class="id_link">#</a></dt><dd><p>
53 Parse a numeric type from its string notation.
54 </p><pre class="synopsis">
55 numeric *PGTYPESnumeric_from_asc(char *str, char **endptr);
57 Valid formats are for example:
58 <code class="literal">-2</code>,
59 <code class="literal">.794</code>,
60 <code class="literal">+3.44</code>,
61 <code class="literal">592.49E07</code> or
62 <code class="literal">-32.84e-4</code>.
63 If the value could be parsed successfully, a valid pointer is returned,
64 else the NULL pointer. At the moment ECPG always parses the complete
65 string and so it currently does not support to store the address of the
66 first invalid character in <code class="literal">*endptr</code>. You can safely
67 set <code class="literal">endptr</code> to NULL.
68 </p></dd><dt id="ECPG-PGTYPES-NUMERIC-TO-ASC"><span class="term"><code class="function">PGTYPESnumeric_to_asc</code></span> <a href="#ECPG-PGTYPES-NUMERIC-TO-ASC" class="id_link">#</a></dt><dd><p>
69 Returns a pointer to a string allocated by <code class="function">malloc</code> that contains the string
70 representation of the numeric type <code class="literal">num</code>.
71 </p><pre class="synopsis">
72 char *PGTYPESnumeric_to_asc(numeric *num, int dscale);
74 The numeric value will be printed with <code class="literal">dscale</code> decimal
75 digits, with rounding applied if necessary.
76 The result must be freed with <code class="function">PGTYPESchar_free()</code>.
77 </p></dd><dt id="ECPG-PGTYPES-NUMERIC-ADD"><span class="term"><code class="function">PGTYPESnumeric_add</code></span> <a href="#ECPG-PGTYPES-NUMERIC-ADD" class="id_link">#</a></dt><dd><p>
78 Add two numeric variables into a third one.
79 </p><pre class="synopsis">
80 int PGTYPESnumeric_add(numeric *var1, numeric *var2, numeric *result);
82 The function adds the variables <code class="literal">var1</code> and
83 <code class="literal">var2</code> into the result variable
84 <code class="literal">result</code>.
85 The function returns 0 on success and -1 in case of error.
86 </p></dd><dt id="ECPG-PGTYPES-NUMERIC-SUB"><span class="term"><code class="function">PGTYPESnumeric_sub</code></span> <a href="#ECPG-PGTYPES-NUMERIC-SUB" class="id_link">#</a></dt><dd><p>
87 Subtract two numeric variables and return the result in a third one.
88 </p><pre class="synopsis">
89 int PGTYPESnumeric_sub(numeric *var1, numeric *var2, numeric *result);
91 The function subtracts the variable <code class="literal">var2</code> from
92 the variable <code class="literal">var1</code>. The result of the operation is
93 stored in the variable <code class="literal">result</code>.
94 The function returns 0 on success and -1 in case of error.
95 </p></dd><dt id="ECPG-PGTYPES-NUMERIC-MUL"><span class="term"><code class="function">PGTYPESnumeric_mul</code></span> <a href="#ECPG-PGTYPES-NUMERIC-MUL" class="id_link">#</a></dt><dd><p>
96 Multiply two numeric variables and return the result in a third one.
97 </p><pre class="synopsis">
98 int PGTYPESnumeric_mul(numeric *var1, numeric *var2, numeric *result);
100 The function multiplies the variables <code class="literal">var1</code> and
101 <code class="literal">var2</code>. The result of the operation is stored in the
102 variable <code class="literal">result</code>.
103 The function returns 0 on success and -1 in case of error.
104 </p></dd><dt id="ECPG-PGTYPES-NUMERIC-DIV"><span class="term"><code class="function">PGTYPESnumeric_div</code></span> <a href="#ECPG-PGTYPES-NUMERIC-DIV" class="id_link">#</a></dt><dd><p>
105 Divide two numeric variables and return the result in a third one.
106 </p><pre class="synopsis">
107 int PGTYPESnumeric_div(numeric *var1, numeric *var2, numeric *result);
109 The function divides the variables <code class="literal">var1</code> by
110 <code class="literal">var2</code>. The result of the operation is stored in the
111 variable <code class="literal">result</code>.
112 The function returns 0 on success and -1 in case of error.
113 </p></dd><dt id="ECPG-PGTYPES-NUMERIC-CMP"><span class="term"><code class="function">PGTYPESnumeric_cmp</code></span> <a href="#ECPG-PGTYPES-NUMERIC-CMP" class="id_link">#</a></dt><dd><p>
114 Compare two numeric variables.
115 </p><pre class="synopsis">
116 int PGTYPESnumeric_cmp(numeric *var1, numeric *var2)
118 This function compares two numeric variables. In case of error,
119 <code class="literal">INT_MAX</code> is returned. On success, the function
120 returns one of three possible results:
121 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
122 1, if <code class="literal">var1</code> is bigger than <code class="literal">var2</code>
123 </p></li><li class="listitem"><p>
124 -1, if <code class="literal">var1</code> is smaller than <code class="literal">var2</code>
125 </p></li><li class="listitem"><p>
126 0, if <code class="literal">var1</code> and <code class="literal">var2</code> are equal
127 </p></li></ul></div><p>
128 </p></dd><dt id="ECPG-PGTYPES-NUMERIC-FROM-INT"><span class="term"><code class="function">PGTYPESnumeric_from_int</code></span> <a href="#ECPG-PGTYPES-NUMERIC-FROM-INT" class="id_link">#</a></dt><dd><p>
129 Convert an int variable to a numeric variable.
130 </p><pre class="synopsis">
131 int PGTYPESnumeric_from_int(signed int int_val, numeric *var);
133 This function accepts a variable of type signed int and stores it
134 in the numeric variable <code class="literal">var</code>. Upon success, 0 is returned and
135 -1 in case of a failure.
136 </p></dd><dt id="ECPG-PGTYPES-NUMERIC-FROM-LONG"><span class="term"><code class="function">PGTYPESnumeric_from_long</code></span> <a href="#ECPG-PGTYPES-NUMERIC-FROM-LONG" class="id_link">#</a></dt><dd><p>
137 Convert a long int variable to a numeric variable.
138 </p><pre class="synopsis">
139 int PGTYPESnumeric_from_long(signed long int long_val, numeric *var);
141 This function accepts a variable of type signed long int and stores it
142 in the numeric variable <code class="literal">var</code>. Upon success, 0 is returned and
143 -1 in case of a failure.
144 </p></dd><dt id="ECPG-PGTYPES-NUMERIC-COPY"><span class="term"><code class="function">PGTYPESnumeric_copy</code></span> <a href="#ECPG-PGTYPES-NUMERIC-COPY" class="id_link">#</a></dt><dd><p>
145 Copy over one numeric variable into another one.
146 </p><pre class="synopsis">
147 int PGTYPESnumeric_copy(numeric *src, numeric *dst);
149 This function copies over the value of the variable that
150 <code class="literal">src</code> points to into the variable that <code class="literal">dst</code>
151 points to. It returns 0 on success and -1 if an error occurs.
152 </p></dd><dt id="ECPG-PGTYPES-NUMERIC-FROM-DOUBLE"><span class="term"><code class="function">PGTYPESnumeric_from_double</code></span> <a href="#ECPG-PGTYPES-NUMERIC-FROM-DOUBLE" class="id_link">#</a></dt><dd><p>
153 Convert a variable of type double to a numeric.
154 </p><pre class="synopsis">
155 int PGTYPESnumeric_from_double(double d, numeric *dst);
157 This function accepts a variable of type double and stores the result
158 in the variable that <code class="literal">dst</code> points to. It returns 0 on success
159 and -1 if an error occurs.
160 </p></dd><dt id="ECPG-PGTYPES-NUMERIC-TO-DOUBLE"><span class="term"><code class="function">PGTYPESnumeric_to_double</code></span> <a href="#ECPG-PGTYPES-NUMERIC-TO-DOUBLE" class="id_link">#</a></dt><dd><p>
161 Convert a variable of type numeric to double.
162 </p><pre class="synopsis">
163 int PGTYPESnumeric_to_double(numeric *nv, double *dp)
165 The function converts the numeric value from the variable that
166 <code class="literal">nv</code> points to into the double variable that <code class="literal">dp</code> points
167 to. It returns 0 on success and -1 if an error occurs, including
168 overflow. On overflow, the global variable <code class="literal">errno</code> will be set
169 to <code class="literal">PGTYPES_NUM_OVERFLOW</code> additionally.
170 </p></dd><dt id="ECPG-PGTYPES-NUMERIC-TO-INT"><span class="term"><code class="function">PGTYPESnumeric_to_int</code></span> <a href="#ECPG-PGTYPES-NUMERIC-TO-INT" class="id_link">#</a></dt><dd><p>
171 Convert a variable of type numeric to int.
172 </p><pre class="synopsis">
173 int PGTYPESnumeric_to_int(numeric *nv, int *ip);
175 The function converts the numeric value from the variable that
176 <code class="literal">nv</code> points to into the integer variable that <code class="literal">ip</code>
177 points to. It returns 0 on success and -1 if an error occurs, including
178 overflow. On overflow, the global variable <code class="literal">errno</code> will be set
179 to <code class="literal">PGTYPES_NUM_OVERFLOW</code> additionally.
180 </p></dd><dt id="ECPG-PGTYPES-NUMERIC-TO-LONG"><span class="term"><code class="function">PGTYPESnumeric_to_long</code></span> <a href="#ECPG-PGTYPES-NUMERIC-TO-LONG" class="id_link">#</a></dt><dd><p>
181 Convert a variable of type numeric to long.
182 </p><pre class="synopsis">
183 int PGTYPESnumeric_to_long(numeric *nv, long *lp);
185 The function converts the numeric value from the variable that
186 <code class="literal">nv</code> points to into the long integer variable that
187 <code class="literal">lp</code> points to. It returns 0 on success and -1 if an error
188 occurs, including overflow and underflow. On overflow, the global variable
189 <code class="literal">errno</code> will be set to <code class="literal">PGTYPES_NUM_OVERFLOW</code>
190 and on underflow <code class="literal">errno</code> will be set to
191 <code class="literal">PGTYPES_NUM_UNDERFLOW</code>.
192 </p></dd><dt id="ECPG-PGTYPES-NUMERIC-TO-DECIMAL"><span class="term"><code class="function">PGTYPESnumeric_to_decimal</code></span> <a href="#ECPG-PGTYPES-NUMERIC-TO-DECIMAL" class="id_link">#</a></dt><dd><p>
193 Convert a variable of type numeric to decimal.
194 </p><pre class="synopsis">
195 int PGTYPESnumeric_to_decimal(numeric *src, decimal *dst);
197 The function converts the numeric value from the variable that
198 <code class="literal">src</code> points to into the decimal variable that
199 <code class="literal">dst</code> points to. It returns 0 on success and -1 if an error
200 occurs, including overflow. On overflow, the global variable
201 <code class="literal">errno</code> will be set to <code class="literal">PGTYPES_NUM_OVERFLOW</code>
203 </p></dd><dt id="ECPG-PGTYPES-NUMERIC-FROM-DECIMAL"><span class="term"><code class="function">PGTYPESnumeric_from_decimal</code></span> <a href="#ECPG-PGTYPES-NUMERIC-FROM-DECIMAL" class="id_link">#</a></dt><dd><p>
204 Convert a variable of type decimal to numeric.
205 </p><pre class="synopsis">
206 int PGTYPESnumeric_from_decimal(decimal *src, numeric *dst);
208 The function converts the decimal value from the variable that
209 <code class="literal">src</code> points to into the numeric variable that
210 <code class="literal">dst</code> points to. It returns 0 on success and -1 if an error
211 occurs. Since the decimal type is implemented as a limited version of
212 the numeric type, overflow cannot occur with this conversion.
213 </p></dd></dl></div><p>
214 </p></div><div class="sect2" id="ECPG-PGTYPES-DATE"><div class="titlepage"><div><div><h3 class="title">34.6.3. The date Type <a href="#ECPG-PGTYPES-DATE" class="id_link">#</a></h3></div></div></div><p>
215 The date type in C enables your programs to deal with data of the SQL type
216 date. See <a class="xref" href="datatype-datetime.html" title="8.5. Date/Time Types">Section 8.5</a> for the equivalent type in the
217 <span class="productname">PostgreSQL</span> server.
219 The following functions can be used to work with the date type:
220 </p><div class="variablelist"><dl class="variablelist"><dt id="PGTYPESDATEFROMTIMESTAMP"><span class="term"><code class="function">PGTYPESdate_from_timestamp</code></span> <a href="#PGTYPESDATEFROMTIMESTAMP" class="id_link">#</a></dt><dd><p>
221 Extract the date part from a timestamp.
222 </p><pre class="synopsis">
223 date PGTYPESdate_from_timestamp(timestamp dt);
225 The function receives a timestamp as its only argument and returns the
226 extracted date part from this timestamp.
227 </p></dd><dt id="PGTYPESDATEFROMASC"><span class="term"><code class="function">PGTYPESdate_from_asc</code></span> <a href="#PGTYPESDATEFROMASC" class="id_link">#</a></dt><dd><p>
228 Parse a date from its textual representation.
229 </p><pre class="synopsis">
230 date PGTYPESdate_from_asc(char *str, char **endptr);
232 The function receives a C char* string <code class="literal">str</code> and a pointer to
233 a C char* string <code class="literal">endptr</code>. At the moment ECPG always parses
234 the complete string and so it currently does not support to store the
235 address of the first invalid character in <code class="literal">*endptr</code>.
236 You can safely set <code class="literal">endptr</code> to NULL.
238 Note that the function always assumes MDY-formatted dates and there is
239 currently no variable to change that within ECPG.
241 <a class="xref" href="ecpg-pgtypes.html#ECPG-PGTYPESDATE-FROM-ASC-TABLE" title="Table 34.2. Valid Input Formats for PGTYPESdate_from_asc">Table 34.2</a> shows the allowed input formats.
242 </p><div class="table" id="ECPG-PGTYPESDATE-FROM-ASC-TABLE"><p class="title"><strong>Table 34.2. Valid Input Formats for <code class="function">PGTYPESdate_from_asc</code></strong></p><div class="table-contents"><table class="table" summary="Valid Input Formats for PGTYPESdate_from_asc" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Input</th><th>Result</th></tr></thead><tbody><tr><td><code class="literal">January 8, 1999</code></td><td><code class="literal">January 8, 1999</code></td></tr><tr><td><code class="literal">1999-01-08</code></td><td><code class="literal">January 8, 1999</code></td></tr><tr><td><code class="literal">1/8/1999</code></td><td><code class="literal">January 8, 1999</code></td></tr><tr><td><code class="literal">1/18/1999</code></td><td><code class="literal">January 18, 1999</code></td></tr><tr><td><code class="literal">01/02/03</code></td><td><code class="literal">February 1, 2003</code></td></tr><tr><td><code class="literal">1999-Jan-08</code></td><td><code class="literal">January 8, 1999</code></td></tr><tr><td><code class="literal">Jan-08-1999</code></td><td><code class="literal">January 8, 1999</code></td></tr><tr><td><code class="literal">08-Jan-1999</code></td><td><code class="literal">January 8, 1999</code></td></tr><tr><td><code class="literal">99-Jan-08</code></td><td><code class="literal">January 8, 1999</code></td></tr><tr><td><code class="literal">08-Jan-99</code></td><td><code class="literal">January 8, 1999</code></td></tr><tr><td><code class="literal">08-Jan-06</code></td><td><code class="literal">January 8, 2006</code></td></tr><tr><td><code class="literal">Jan-08-99</code></td><td><code class="literal">January 8, 1999</code></td></tr><tr><td><code class="literal">19990108</code></td><td><code class="literal">ISO 8601; January 8, 1999</code></td></tr><tr><td><code class="literal">990108</code></td><td><code class="literal">ISO 8601; January 8, 1999</code></td></tr><tr><td><code class="literal">1999.008</code></td><td><code class="literal">year and day of year</code></td></tr><tr><td><code class="literal">J2451187</code></td><td><code class="literal">Julian day</code></td></tr><tr><td><code class="literal">January 8, 99 BC</code></td><td><code class="literal">year 99 before the Common Era</code></td></tr></tbody></table></div></div><br class="table-break" /></dd><dt id="PGTYPESDATETOASC"><span class="term"><code class="function">PGTYPESdate_to_asc</code></span> <a href="#PGTYPESDATETOASC" class="id_link">#</a></dt><dd><p>
243 Return the textual representation of a date variable.
244 </p><pre class="synopsis">
245 char *PGTYPESdate_to_asc(date dDate);
247 The function receives the date <code class="literal">dDate</code> as its only parameter.
248 It will output the date in the form <code class="literal">1999-01-18</code>, i.e., in the
249 <code class="literal">YYYY-MM-DD</code> format.
250 The result must be freed with <code class="function">PGTYPESchar_free()</code>.
251 </p></dd><dt id="PGTYPESDATEJULMDY"><span class="term"><code class="function">PGTYPESdate_julmdy</code></span> <a href="#PGTYPESDATEJULMDY" class="id_link">#</a></dt><dd><p>
252 Extract the values for the day, the month and the year from a variable
254 </p><pre class="synopsis">
255 void PGTYPESdate_julmdy(date d, int *mdy);
258 The function receives the date <code class="literal">d</code> and a pointer to an array
259 of 3 integer values <code class="literal">mdy</code>. The variable name indicates
260 the sequential order: <code class="literal">mdy[0]</code> will be set to contain the
261 number of the month, <code class="literal">mdy[1]</code> will be set to the value of the
262 day and <code class="literal">mdy[2]</code> will contain the year.
263 </p></dd><dt id="PGTYPESDATEMDYJUL"><span class="term"><code class="function">PGTYPESdate_mdyjul</code></span> <a href="#PGTYPESDATEMDYJUL" class="id_link">#</a></dt><dd><p>
264 Create a date value from an array of 3 integers that specify the
265 day, the month and the year of the date.
266 </p><pre class="synopsis">
267 void PGTYPESdate_mdyjul(int *mdy, date *jdate);
269 The function receives the array of the 3 integers (<code class="literal">mdy</code>) as
270 its first argument and as its second argument a pointer to a variable
271 of type date that should hold the result of the operation.
272 </p></dd><dt id="PGTYPESDATEDAYOFWEEK"><span class="term"><code class="function">PGTYPESdate_dayofweek</code></span> <a href="#PGTYPESDATEDAYOFWEEK" class="id_link">#</a></dt><dd><p>
273 Return a number representing the day of the week for a date value.
274 </p><pre class="synopsis">
275 int PGTYPESdate_dayofweek(date d);
277 The function receives the date variable <code class="literal">d</code> as its only
278 argument and returns an integer that indicates the day of the week for
280 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
282 </p></li><li class="listitem"><p>
284 </p></li><li class="listitem"><p>
286 </p></li><li class="listitem"><p>
288 </p></li><li class="listitem"><p>
290 </p></li><li class="listitem"><p>
292 </p></li><li class="listitem"><p>
294 </p></li></ul></div><p>
295 </p></dd><dt id="PGTYPESDATETODAY"><span class="term"><code class="function">PGTYPESdate_today</code></span> <a href="#PGTYPESDATETODAY" class="id_link">#</a></dt><dd><p>
296 Get the current date.
297 </p><pre class="synopsis">
298 void PGTYPESdate_today(date *d);
300 The function receives a pointer to a date variable (<code class="literal">d</code>)
301 that it sets to the current date.
302 </p></dd><dt id="PGTYPESDATEFMTASC"><span class="term"><code class="function">PGTYPESdate_fmt_asc</code></span> <a href="#PGTYPESDATEFMTASC" class="id_link">#</a></dt><dd><p>
303 Convert a variable of type date to its textual representation using a
305 </p><pre class="synopsis">
306 int PGTYPESdate_fmt_asc(date dDate, char *fmtstring, char *outbuf);
308 The function receives the date to convert (<code class="literal">dDate</code>), the
309 format mask (<code class="literal">fmtstring</code>) and the string that will hold the
310 textual representation of the date (<code class="literal">outbuf</code>).
312 On success, 0 is returned and a negative value if an error occurred.
314 The following literals are the field specifiers you can use:
315 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
316 <code class="literal">dd</code> - The number of the day of the month.
317 </p></li><li class="listitem"><p>
318 <code class="literal">mm</code> - The number of the month of the year.
319 </p></li><li class="listitem"><p>
320 <code class="literal">yy</code> - The number of the year as a two digit number.
321 </p></li><li class="listitem"><p>
322 <code class="literal">yyyy</code> - The number of the year as a four digit number.
323 </p></li><li class="listitem"><p>
324 <code class="literal">ddd</code> - The name of the day (abbreviated).
325 </p></li><li class="listitem"><p>
326 <code class="literal">mmm</code> - The name of the month (abbreviated).
327 </p></li></ul></div><p>
328 All other characters are copied 1:1 to the output string.
330 <a class="xref" href="ecpg-pgtypes.html#ECPG-PGTYPESDATE-FMT-ASC-EXAMPLE-TABLE" title="Table 34.3. Valid Input Formats for PGTYPESdate_fmt_asc">Table 34.3</a> indicates a few possible formats. This will give
331 you an idea of how to use this function. All output lines are based on
332 the same date: November 23, 1959.
333 </p><div class="table" id="ECPG-PGTYPESDATE-FMT-ASC-EXAMPLE-TABLE"><p class="title"><strong>Table 34.3. Valid Input Formats for <code class="function">PGTYPESdate_fmt_asc</code></strong></p><div class="table-contents"><table class="table" summary="Valid Input Formats for PGTYPESdate_fmt_asc" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Format</th><th>Result</th></tr></thead><tbody><tr><td><code class="literal">mmddyy</code></td><td><code class="literal">112359</code></td></tr><tr><td><code class="literal">ddmmyy</code></td><td><code class="literal">231159</code></td></tr><tr><td><code class="literal">yymmdd</code></td><td><code class="literal">591123</code></td></tr><tr><td><code class="literal">yy/mm/dd</code></td><td><code class="literal">59/11/23</code></td></tr><tr><td><code class="literal">yy mm dd</code></td><td><code class="literal">59 11 23</code></td></tr><tr><td><code class="literal">yy.mm.dd</code></td><td><code class="literal">59.11.23</code></td></tr><tr><td><code class="literal">.mm.yyyy.dd.</code></td><td><code class="literal">.11.1959.23.</code></td></tr><tr><td><code class="literal">mmm. dd, yyyy</code></td><td><code class="literal">Nov. 23, 1959</code></td></tr><tr><td><code class="literal">mmm dd yyyy</code></td><td><code class="literal">Nov 23 1959</code></td></tr><tr><td><code class="literal">yyyy dd mm</code></td><td><code class="literal">1959 23 11</code></td></tr><tr><td><code class="literal">ddd, mmm. dd, yyyy</code></td><td><code class="literal">Mon, Nov. 23, 1959</code></td></tr><tr><td><code class="literal">(ddd) mmm. dd, yyyy</code></td><td><code class="literal">(Mon) Nov. 23, 1959</code></td></tr></tbody></table></div></div><br class="table-break" /></dd><dt id="PGTYPESDATEDEFMTASC"><span class="term"><code class="function">PGTYPESdate_defmt_asc</code></span> <a href="#PGTYPESDATEDEFMTASC" class="id_link">#</a></dt><dd><p>
334 Use a format mask to convert a C <code class="type">char*</code> string to a value of type
336 </p><pre class="synopsis">
337 int PGTYPESdate_defmt_asc(date *d, char *fmt, char *str);
340 The function receives a pointer to the date value that should hold the
341 result of the operation (<code class="literal">d</code>), the format mask to use for
342 parsing the date (<code class="literal">fmt</code>) and the C char* string containing
343 the textual representation of the date (<code class="literal">str</code>). The textual
344 representation is expected to match the format mask. However you do not
345 need to have a 1:1 mapping of the string to the format mask. The
346 function only analyzes the sequential order and looks for the literals
347 <code class="literal">yy</code> or <code class="literal">yyyy</code> that indicate the
348 position of the year, <code class="literal">mm</code> to indicate the position of
349 the month and <code class="literal">dd</code> to indicate the position of the
352 <a class="xref" href="ecpg-pgtypes.html#ECPG-RDEFMTDATE-EXAMPLE-TABLE" title="Table 34.4. Valid Input Formats for rdefmtdate">Table 34.4</a> indicates a few possible formats. This will give
353 you an idea of how to use this function.
354 </p><div class="table" id="ECPG-RDEFMTDATE-EXAMPLE-TABLE"><p class="title"><strong>Table 34.4. Valid Input Formats for <code class="function">rdefmtdate</code></strong></p><div class="table-contents"><table class="table" summary="Valid Input Formats for rdefmtdate" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Format</th><th>String</th><th>Result</th></tr></thead><tbody><tr><td><code class="literal">ddmmyy</code></td><td><code class="literal">21-2-54</code></td><td><code class="literal">1954-02-21</code></td></tr><tr><td><code class="literal">ddmmyy</code></td><td><code class="literal">2-12-54</code></td><td><code class="literal">1954-12-02</code></td></tr><tr><td><code class="literal">ddmmyy</code></td><td><code class="literal">20111954</code></td><td><code class="literal">1954-11-20</code></td></tr><tr><td><code class="literal">ddmmyy</code></td><td><code class="literal">130464</code></td><td><code class="literal">1964-04-13</code></td></tr><tr><td><code class="literal">mmm.dd.yyyy</code></td><td><code class="literal">MAR-12-1967</code></td><td><code class="literal">1967-03-12</code></td></tr><tr><td><code class="literal">yy/mm/dd</code></td><td><code class="literal">1954, February 3rd</code></td><td><code class="literal">1954-02-03</code></td></tr><tr><td><code class="literal">mmm.dd.yyyy</code></td><td><code class="literal">041269</code></td><td><code class="literal">1969-04-12</code></td></tr><tr><td><code class="literal">yy/mm/dd</code></td><td><code class="literal">In the year 2525, in the month of July, mankind will be alive on the 28th day</code></td><td><code class="literal">2525-07-28</code></td></tr><tr><td><code class="literal">dd-mm-yy</code></td><td><code class="literal">I said on the 28th of July in the year 2525</code></td><td><code class="literal">2525-07-28</code></td></tr><tr><td><code class="literal">mmm.dd.yyyy</code></td><td><code class="literal">9/14/58</code></td><td><code class="literal">1958-09-14</code></td></tr><tr><td><code class="literal">yy/mm/dd</code></td><td><code class="literal">47/03/29</code></td><td><code class="literal">1947-03-29</code></td></tr><tr><td><code class="literal">mmm.dd.yyyy</code></td><td><code class="literal">oct 28 1975</code></td><td><code class="literal">1975-10-28</code></td></tr><tr><td><code class="literal">mmddyy</code></td><td><code class="literal">Nov 14th, 1985</code></td><td><code class="literal">1985-11-14</code></td></tr></tbody></table></div></div><br class="table-break" /></dd></dl></div><p>
355 </p></div><div class="sect2" id="ECPG-PGTYPES-TIMESTAMP"><div class="titlepage"><div><div><h3 class="title">34.6.4. The timestamp Type <a href="#ECPG-PGTYPES-TIMESTAMP" class="id_link">#</a></h3></div></div></div><p>
356 The timestamp type in C enables your programs to deal with data of the SQL
357 type timestamp. See <a class="xref" href="datatype-datetime.html" title="8.5. Date/Time Types">Section 8.5</a> for the equivalent
358 type in the <span class="productname">PostgreSQL</span> server.
360 The following functions can be used to work with the timestamp type:
361 </p><div class="variablelist"><dl class="variablelist"><dt id="PGTYPESTIMESTAMPFROMASC"><span class="term"><code class="function">PGTYPEStimestamp_from_asc</code></span> <a href="#PGTYPESTIMESTAMPFROMASC" class="id_link">#</a></dt><dd><p>
362 Parse a timestamp from its textual representation into a timestamp
364 </p><pre class="synopsis">
365 timestamp PGTYPEStimestamp_from_asc(char *str, char **endptr);
367 The function receives the string to parse (<code class="literal">str</code>) and a
368 pointer to a C char* (<code class="literal">endptr</code>).
369 At the moment ECPG always parses
370 the complete string and so it currently does not support to store the
371 address of the first invalid character in <code class="literal">*endptr</code>.
372 You can safely set <code class="literal">endptr</code> to NULL.
374 The function returns the parsed timestamp on success. On error,
375 <code class="literal">PGTYPESInvalidTimestamp</code> is returned and <code class="varname">errno</code> is
376 set to <code class="literal">PGTYPES_TS_BAD_TIMESTAMP</code>. See <a class="xref" href="ecpg-pgtypes.html#PGTYPESINVALIDTIMESTAMP"><code class="literal">PGTYPESInvalidTimestamp</code></a> for important notes on this value.
378 In general, the input string can contain any combination of an allowed
379 date specification, a whitespace character and an allowed time
380 specification. Note that time zones are not supported by ECPG. It can
381 parse them but does not apply any calculation as the
382 <span class="productname">PostgreSQL</span> server does for example. Timezone
383 specifiers are silently discarded.
385 <a class="xref" href="ecpg-pgtypes.html#ECPG-PGTYPESTIMESTAMP-FROM-ASC-EXAMPLE-TABLE" title="Table 34.5. Valid Input Formats for PGTYPEStimestamp_from_asc">Table 34.5</a> contains a few examples for input strings.
386 </p><div class="table" id="ECPG-PGTYPESTIMESTAMP-FROM-ASC-EXAMPLE-TABLE"><p class="title"><strong>Table 34.5. Valid Input Formats for <code class="function">PGTYPEStimestamp_from_asc</code></strong></p><div class="table-contents"><table class="table" summary="Valid Input Formats for PGTYPEStimestamp_from_asc" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Input</th><th>Result</th></tr></thead><tbody><tr><td><code class="literal">1999-01-08 04:05:06</code></td><td><code class="literal">1999-01-08 04:05:06</code></td></tr><tr><td><code class="literal">January 8 04:05:06 1999 PST</code></td><td><code class="literal">1999-01-08 04:05:06</code></td></tr><tr><td><code class="literal">1999-Jan-08 04:05:06.789-8</code></td><td><code class="literal">1999-01-08 04:05:06.789 (time zone specifier ignored)</code></td></tr><tr><td><code class="literal">J2451187 04:05-08:00</code></td><td><code class="literal">1999-01-08 04:05:00 (time zone specifier ignored)</code></td></tr></tbody></table></div></div><br class="table-break" /></dd><dt id="PGTYPESTIMESTAMPTOASC"><span class="term"><code class="function">PGTYPEStimestamp_to_asc</code></span> <a href="#PGTYPESTIMESTAMPTOASC" class="id_link">#</a></dt><dd><p>
387 Converts a date to a C char* string.
388 </p><pre class="synopsis">
389 char *PGTYPEStimestamp_to_asc(timestamp tstamp);
391 The function receives the timestamp <code class="literal">tstamp</code> as
392 its only argument and returns an allocated string that contains the
393 textual representation of the timestamp.
394 The result must be freed with <code class="function">PGTYPESchar_free()</code>.
395 </p></dd><dt id="PGTYPESTIMESTAMPCURRENT"><span class="term"><code class="function">PGTYPEStimestamp_current</code></span> <a href="#PGTYPESTIMESTAMPCURRENT" class="id_link">#</a></dt><dd><p>
396 Retrieve the current timestamp.
397 </p><pre class="synopsis">
398 void PGTYPEStimestamp_current(timestamp *ts);
400 The function retrieves the current timestamp and saves it into the
401 timestamp variable that <code class="literal">ts</code> points to.
402 </p></dd><dt id="PGTYPESTIMESTAMPFMTASC"><span class="term"><code class="function">PGTYPEStimestamp_fmt_asc</code></span> <a href="#PGTYPESTIMESTAMPFMTASC" class="id_link">#</a></dt><dd><p>
403 Convert a timestamp variable to a C char* using a format mask.
404 </p><pre class="synopsis">
405 int PGTYPEStimestamp_fmt_asc(timestamp *ts, char *output, int str_len, char *fmtstr);
407 The function receives a pointer to the timestamp to convert as its
408 first argument (<code class="literal">ts</code>), a pointer to the output buffer
409 (<code class="literal">output</code>), the maximal length that has been allocated for
410 the output buffer (<code class="literal">str_len</code>) and the format mask to
411 use for the conversion (<code class="literal">fmtstr</code>).
413 Upon success, the function returns 0 and a negative value if an
416 You can use the following format specifiers for the format mask. The
417 format specifiers are the same ones that are used in the
418 <code class="function">strftime</code> function in <span class="productname">libc</span>. Any
419 non-format specifier will be copied into the output buffer.
421 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
422 <code class="literal">%A</code> - is replaced by national representation of
423 the full weekday name.
424 </p></li><li class="listitem"><p>
425 <code class="literal">%a</code> - is replaced by national representation of
426 the abbreviated weekday name.
427 </p></li><li class="listitem"><p>
428 <code class="literal">%B</code> - is replaced by national representation of
430 </p></li><li class="listitem"><p>
431 <code class="literal">%b</code> - is replaced by national representation of
432 the abbreviated month name.
433 </p></li><li class="listitem"><p>
434 <code class="literal">%C</code> - is replaced by (year / 100) as decimal
435 number; single digits are preceded by a zero.
436 </p></li><li class="listitem"><p>
437 <code class="literal">%c</code> - is replaced by national representation of
439 </p></li><li class="listitem"><p>
440 <code class="literal">%D</code> - is equivalent to
441 <code class="literal">%m/%d/%y</code>.
442 </p></li><li class="listitem"><p>
443 <code class="literal">%d</code> - is replaced by the day of the month as a
444 decimal number (01–31).
445 </p></li><li class="listitem"><p>
446 <code class="literal">%E*</code> <code class="literal">%O*</code> - POSIX locale
447 extensions. The sequences
448 <code class="literal">%Ec</code>
449 <code class="literal">%EC</code>
450 <code class="literal">%Ex</code>
451 <code class="literal">%EX</code>
452 <code class="literal">%Ey</code>
453 <code class="literal">%EY</code>
454 <code class="literal">%Od</code>
455 <code class="literal">%Oe</code>
456 <code class="literal">%OH</code>
457 <code class="literal">%OI</code>
458 <code class="literal">%Om</code>
459 <code class="literal">%OM</code>
460 <code class="literal">%OS</code>
461 <code class="literal">%Ou</code>
462 <code class="literal">%OU</code>
463 <code class="literal">%OV</code>
464 <code class="literal">%Ow</code>
465 <code class="literal">%OW</code>
466 <code class="literal">%Oy</code>
467 are supposed to provide alternative representations.
469 Additionally <code class="literal">%OB</code> implemented to represent
470 alternative months names (used standalone, without day mentioned).
471 </p></li><li class="listitem"><p>
472 <code class="literal">%e</code> - is replaced by the day of month as a decimal
473 number (1–31); single digits are preceded by a blank.
474 </p></li><li class="listitem"><p>
475 <code class="literal">%F</code> - is equivalent to <code class="literal">%Y-%m-%d</code>.
476 </p></li><li class="listitem"><p>
477 <code class="literal">%G</code> - is replaced by a year as a decimal number
478 with century. This year is the one that contains the greater part of
479 the week (Monday as the first day of the week).
480 </p></li><li class="listitem"><p>
481 <code class="literal">%g</code> - is replaced by the same year as in
482 <code class="literal">%G</code>, but as a decimal number without century
484 </p></li><li class="listitem"><p>
485 <code class="literal">%H</code> - is replaced by the hour (24-hour clock) as a
486 decimal number (00–23).
487 </p></li><li class="listitem"><p>
488 <code class="literal">%h</code> - the same as <code class="literal">%b</code>.
489 </p></li><li class="listitem"><p>
490 <code class="literal">%I</code> - is replaced by the hour (12-hour clock) as a
491 decimal number (01–12).
492 </p></li><li class="listitem"><p>
493 <code class="literal">%j</code> - is replaced by the day of the year as a
494 decimal number (001–366).
495 </p></li><li class="listitem"><p>
496 <code class="literal">%k</code> - is replaced by the hour (24-hour clock) as a
497 decimal number (0–23); single digits are preceded by a blank.
498 </p></li><li class="listitem"><p>
499 <code class="literal">%l</code> - is replaced by the hour (12-hour clock) as a
500 decimal number (1–12); single digits are preceded by a blank.
501 </p></li><li class="listitem"><p>
502 <code class="literal">%M</code> - is replaced by the minute as a decimal
504 </p></li><li class="listitem"><p>
505 <code class="literal">%m</code> - is replaced by the month as a decimal number
507 </p></li><li class="listitem"><p>
508 <code class="literal">%n</code> - is replaced by a newline.
509 </p></li><li class="listitem"><p>
510 <code class="literal">%O*</code> - the same as <code class="literal">%E*</code>.
511 </p></li><li class="listitem"><p>
512 <code class="literal">%p</code> - is replaced by national representation of
513 either <span class="quote">“<span class="quote">ante meridiem</span>”</span> or <span class="quote">“<span class="quote">post meridiem</span>”</span> as appropriate.
514 </p></li><li class="listitem"><p>
515 <code class="literal">%R</code> - is equivalent to <code class="literal">%H:%M</code>.
516 </p></li><li class="listitem"><p>
517 <code class="literal">%r</code> - is equivalent to <code class="literal">%I:%M:%S
519 </p></li><li class="listitem"><p>
520 <code class="literal">%S</code> - is replaced by the second as a decimal
522 </p></li><li class="listitem"><p>
523 <code class="literal">%s</code> - is replaced by the number of seconds since
525 </p></li><li class="listitem"><p>
526 <code class="literal">%T</code> - is equivalent to <code class="literal">%H:%M:%S</code>
527 </p></li><li class="listitem"><p>
528 <code class="literal">%t</code> - is replaced by a tab.
529 </p></li><li class="listitem"><p>
530 <code class="literal">%U</code> - is replaced by the week number of the year
531 (Sunday as the first day of the week) as a decimal number (00–53).
532 </p></li><li class="listitem"><p>
533 <code class="literal">%u</code> - is replaced by the weekday (Monday as the
534 first day of the week) as a decimal number (1–7).
535 </p></li><li class="listitem"><p>
536 <code class="literal">%V</code> - is replaced by the week number of the year
537 (Monday as the first day of the week) as a decimal number (01–53).
538 If the week containing January 1 has four or more days in the new
539 year, then it is week 1; otherwise it is the last week of the
540 previous year, and the next week is week 1.
541 </p></li><li class="listitem"><p>
542 <code class="literal">%v</code> - is equivalent to
543 <code class="literal">%e-%b-%Y</code>.
544 </p></li><li class="listitem"><p>
545 <code class="literal">%W</code> - is replaced by the week number of the year
546 (Monday as the first day of the week) as a decimal number (00–53).
547 </p></li><li class="listitem"><p>
548 <code class="literal">%w</code> - is replaced by the weekday (Sunday as the
549 first day of the week) as a decimal number (0–6).
550 </p></li><li class="listitem"><p>
551 <code class="literal">%X</code> - is replaced by national representation of
553 </p></li><li class="listitem"><p>
554 <code class="literal">%x</code> - is replaced by national representation of
556 </p></li><li class="listitem"><p>
557 <code class="literal">%Y</code> - is replaced by the year with century as a
559 </p></li><li class="listitem"><p>
560 <code class="literal">%y</code> - is replaced by the year without century as a
561 decimal number (00–99).
562 </p></li><li class="listitem"><p>
563 <code class="literal">%Z</code> - is replaced by the time zone name.
564 </p></li><li class="listitem"><p>
565 <code class="literal">%z</code> - is replaced by the time zone offset from
566 UTC; a leading plus sign stands for east of UTC, a minus sign for
567 west of UTC, hours and minutes follow with two digits each and no
568 delimiter between them (common form for <a class="ulink" href="https://datatracker.ietf.org/doc/html/rfc822" target="_top">RFC 822</a> date headers).
569 </p></li><li class="listitem"><p>
570 <code class="literal">%+</code> - is replaced by national representation of
572 </p></li><li class="listitem"><p>
573 <code class="literal">%-*</code> - GNU libc extension. Do not do any padding
574 when performing numerical outputs.
575 </p></li><li class="listitem"><p>
576 $_* - GNU libc extension. Explicitly specify space for padding.
577 </p></li><li class="listitem"><p>
578 <code class="literal">%0*</code> - GNU libc extension. Explicitly specify zero
580 </p></li><li class="listitem"><p>
581 <code class="literal">%%</code> - is replaced by <code class="literal">%</code>.
582 </p></li></ul></div><p>
583 </p></dd><dt id="PGTYPESTIMESTAMPSUB"><span class="term"><code class="function">PGTYPEStimestamp_sub</code></span> <a href="#PGTYPESTIMESTAMPSUB" class="id_link">#</a></dt><dd><p>
584 Subtract one timestamp from another one and save the result in a
585 variable of type interval.
586 </p><pre class="synopsis">
587 int PGTYPEStimestamp_sub(timestamp *ts1, timestamp *ts2, interval *iv);
589 The function will subtract the timestamp variable that <code class="literal">ts2</code>
590 points to from the timestamp variable that <code class="literal">ts1</code> points to
591 and will store the result in the interval variable that <code class="literal">iv</code>
594 Upon success, the function returns 0 and a negative value if an
596 </p></dd><dt id="PGTYPESTIMESTAMPDEFMTASC"><span class="term"><code class="function">PGTYPEStimestamp_defmt_asc</code></span> <a href="#PGTYPESTIMESTAMPDEFMTASC" class="id_link">#</a></dt><dd><p>
597 Parse a timestamp value from its textual representation using a
599 </p><pre class="synopsis">
600 int PGTYPEStimestamp_defmt_asc(char *str, char *fmt, timestamp *d);
602 The function receives the textual representation of a timestamp in the
603 variable <code class="literal">str</code> as well as the formatting mask to use in the
604 variable <code class="literal">fmt</code>. The result will be stored in the variable
605 that <code class="literal">d</code> points to.
607 If the formatting mask <code class="literal">fmt</code> is NULL, the function will fall
608 back to the default formatting mask which is <code class="literal">%Y-%m-%d
611 This is the reverse function to <a class="xref" href="ecpg-pgtypes.html#PGTYPESTIMESTAMPFMTASC"><code class="function">PGTYPEStimestamp_fmt_asc</code></a>. See the documentation there in
612 order to find out about the possible formatting mask entries.
613 </p></dd><dt id="PGTYPESTIMESTAMPADDINTERVAL"><span class="term"><code class="function">PGTYPEStimestamp_add_interval</code></span> <a href="#PGTYPESTIMESTAMPADDINTERVAL" class="id_link">#</a></dt><dd><p>
614 Add an interval variable to a timestamp variable.
615 </p><pre class="synopsis">
616 int PGTYPEStimestamp_add_interval(timestamp *tin, interval *span, timestamp *tout);
618 The function receives a pointer to a timestamp variable <code class="literal">tin</code>
619 and a pointer to an interval variable <code class="literal">span</code>. It adds the
620 interval to the timestamp and saves the resulting timestamp in the
621 variable that <code class="literal">tout</code> points to.
623 Upon success, the function returns 0 and a negative value if an
625 </p></dd><dt id="PGTYPESTIMESTAMPSUBINTERVAL"><span class="term"><code class="function">PGTYPEStimestamp_sub_interval</code></span> <a href="#PGTYPESTIMESTAMPSUBINTERVAL" class="id_link">#</a></dt><dd><p>
626 Subtract an interval variable from a timestamp variable.
627 </p><pre class="synopsis">
628 int PGTYPEStimestamp_sub_interval(timestamp *tin, interval *span, timestamp *tout);
630 The function subtracts the interval variable that <code class="literal">span</code>
631 points to from the timestamp variable that <code class="literal">tin</code> points to
632 and saves the result into the variable that <code class="literal">tout</code> points
635 Upon success, the function returns 0 and a negative value if an
637 </p></dd></dl></div><p>
638 </p></div><div class="sect2" id="ECPG-PGTYPES-INTERVAL"><div class="titlepage"><div><div><h3 class="title">34.6.5. The interval Type <a href="#ECPG-PGTYPES-INTERVAL" class="id_link">#</a></h3></div></div></div><p>
639 The interval type in C enables your programs to deal with data of the SQL
640 type interval. See <a class="xref" href="datatype-datetime.html" title="8.5. Date/Time Types">Section 8.5</a> for the equivalent
641 type in the <span class="productname">PostgreSQL</span> server.
643 The following functions can be used to work with the interval type:
644 </p><div class="variablelist"><dl class="variablelist"><dt id="PGTYPESINTERVALNEW"><span class="term"><code class="function">PGTYPESinterval_new</code></span> <a href="#PGTYPESINTERVALNEW" class="id_link">#</a></dt><dd><p>
645 Return a pointer to a newly allocated interval variable.
646 </p><pre class="synopsis">
647 interval *PGTYPESinterval_new(void);
649 </p></dd><dt id="PGTYPESINTERVALFREE"><span class="term"><code class="function">PGTYPESinterval_free</code></span> <a href="#PGTYPESINTERVALFREE" class="id_link">#</a></dt><dd><p>
650 Release the memory of a previously allocated interval variable.
651 </p><pre class="synopsis">
652 void PGTYPESinterval_free(interval *intvl);
654 </p></dd><dt id="PGTYPESINTERVALFROMASC"><span class="term"><code class="function">PGTYPESinterval_from_asc</code></span> <a href="#PGTYPESINTERVALFROMASC" class="id_link">#</a></dt><dd><p>
655 Parse an interval from its textual representation.
656 </p><pre class="synopsis">
657 interval *PGTYPESinterval_from_asc(char *str, char **endptr);
659 The function parses the input string <code class="literal">str</code> and returns a
660 pointer to an allocated interval variable.
661 At the moment ECPG always parses
662 the complete string and so it currently does not support to store the
663 address of the first invalid character in <code class="literal">*endptr</code>.
664 You can safely set <code class="literal">endptr</code> to NULL.
665 </p></dd><dt id="PGTYPESINTERVALTOASC"><span class="term"><code class="function">PGTYPESinterval_to_asc</code></span> <a href="#PGTYPESINTERVALTOASC" class="id_link">#</a></dt><dd><p>
666 Convert a variable of type interval to its textual representation.
667 </p><pre class="synopsis">
668 char *PGTYPESinterval_to_asc(interval *span);
670 The function converts the interval variable that <code class="literal">span</code>
671 points to into a C char*. The output looks like this example:
672 <code class="literal">@ 1 day 12 hours 59 mins 10 secs</code>.
673 The result must be freed with <code class="function">PGTYPESchar_free()</code>.
674 </p></dd><dt id="PGTYPESINTERVALCOPY"><span class="term"><code class="function">PGTYPESinterval_copy</code></span> <a href="#PGTYPESINTERVALCOPY" class="id_link">#</a></dt><dd><p>
675 Copy a variable of type interval.
676 </p><pre class="synopsis">
677 int PGTYPESinterval_copy(interval *intvlsrc, interval *intvldest);
679 The function copies the interval variable that <code class="literal">intvlsrc</code>
680 points to into the variable that <code class="literal">intvldest</code> points to. Note
681 that you need to allocate the memory for the destination variable
683 </p></dd></dl></div><p>
684 </p></div><div class="sect2" id="ECPG-PGTYPES-DECIMAL"><div class="titlepage"><div><div><h3 class="title">34.6.6. The decimal Type <a href="#ECPG-PGTYPES-DECIMAL" class="id_link">#</a></h3></div></div></div><p>
685 The decimal type is similar to the numeric type. However it is limited to
686 a maximum precision of 30 significant digits. In contrast to the numeric
687 type which can be created on the heap only, the decimal type can be
688 created either on the stack or on the heap (by means of the functions
689 <code class="function">PGTYPESdecimal_new</code> and
690 <code class="function">PGTYPESdecimal_free</code>).
691 There are a lot of other functions that deal with the decimal type in the
692 <span class="productname">Informix</span> compatibility mode described in <a class="xref" href="ecpg-informix-compat.html" title="34.15. Informix Compatibility Mode">Section 34.15</a>.
694 The following functions can be used to work with the decimal type and are
695 not only contained in the <code class="literal">libcompat</code> library.
696 </p><div class="variablelist"><dl class="variablelist"><dt id="ECPG-PGTYPES-DECIMAL-NEW"><span class="term"><code class="function">PGTYPESdecimal_new</code></span> <a href="#ECPG-PGTYPES-DECIMAL-NEW" class="id_link">#</a></dt><dd><p>
697 Request a pointer to a newly allocated decimal variable.
698 </p><pre class="synopsis">
699 decimal *PGTYPESdecimal_new(void);
701 </p></dd><dt id="ECPG-PGTYPES-DECIMAL-FREE"><span class="term"><code class="function">PGTYPESdecimal_free</code></span> <a href="#ECPG-PGTYPES-DECIMAL-FREE" class="id_link">#</a></dt><dd><p>
702 Free a decimal type, release all of its memory.
703 </p><pre class="synopsis">
704 void PGTYPESdecimal_free(decimal *var);
706 </p></dd></dl></div><p>
707 </p></div><div class="sect2" id="ECPG-PGTYPES-ERRNO"><div class="titlepage"><div><div><h3 class="title">34.6.7. errno Values of pgtypeslib <a href="#ECPG-PGTYPES-ERRNO" class="id_link">#</a></h3></div></div></div><p>
708 </p><div class="variablelist"><dl class="variablelist"><dt id="ECPG-PGTYPES-ERRNO-PGTYPES-NUM-BAD-NUMERIC"><span class="term"><code class="literal">PGTYPES_NUM_BAD_NUMERIC</code></span> <a href="#ECPG-PGTYPES-ERRNO-PGTYPES-NUM-BAD-NUMERIC" class="id_link">#</a></dt><dd><p>
709 An argument should contain a numeric variable (or point to a numeric
710 variable) but in fact its in-memory representation was invalid.
711 </p></dd><dt id="ECPG-PGTYPES-ERRNO-PGTYPES-NUM-OVERFLOW"><span class="term"><code class="literal">PGTYPES_NUM_OVERFLOW</code></span> <a href="#ECPG-PGTYPES-ERRNO-PGTYPES-NUM-OVERFLOW" class="id_link">#</a></dt><dd><p>
712 An overflow occurred. Since the numeric type can deal with almost
713 arbitrary precision, converting a numeric variable into other types
714 might cause overflow.
715 </p></dd><dt id="ECPG-PGTYPES-ERRNO-PGTYPES-NUM-UNDERFLOW"><span class="term"><code class="literal">PGTYPES_NUM_UNDERFLOW</code></span> <a href="#ECPG-PGTYPES-ERRNO-PGTYPES-NUM-UNDERFLOW" class="id_link">#</a></dt><dd><p>
716 An underflow occurred. Since the numeric type can deal with almost
717 arbitrary precision, converting a numeric variable into other types
718 might cause underflow.
719 </p></dd><dt id="ECPG-PGTYPES-ERRNO-PGTYPES-NUM-DIVIDE-ZERO"><span class="term"><code class="literal">PGTYPES_NUM_DIVIDE_ZERO</code></span> <a href="#ECPG-PGTYPES-ERRNO-PGTYPES-NUM-DIVIDE-ZERO" class="id_link">#</a></dt><dd><p>
720 A division by zero has been attempted.
721 </p></dd><dt id="ECPG-PGTYPES-ERRNO-PGTYPES-DATE-BAD-DATE"><span class="term"><code class="literal">PGTYPES_DATE_BAD_DATE</code></span> <a href="#ECPG-PGTYPES-ERRNO-PGTYPES-DATE-BAD-DATE" class="id_link">#</a></dt><dd><p>
722 An invalid date string was passed to
723 the <code class="function">PGTYPESdate_from_asc</code> function.
724 </p></dd><dt id="ECPG-PGTYPES-ERRNO-PGTYPES-DATE-ERR-EARGS"><span class="term"><code class="literal">PGTYPES_DATE_ERR_EARGS</code></span> <a href="#ECPG-PGTYPES-ERRNO-PGTYPES-DATE-ERR-EARGS" class="id_link">#</a></dt><dd><p>
725 Invalid arguments were passed to the
726 <code class="function">PGTYPESdate_defmt_asc</code> function.
727 </p></dd><dt id="ECPG-PGTYPES-ERRNO-PGTYPES-DATE-ERR-ENOSHORTDATE"><span class="term"><code class="literal">PGTYPES_DATE_ERR_ENOSHORTDATE</code></span> <a href="#ECPG-PGTYPES-ERRNO-PGTYPES-DATE-ERR-ENOSHORTDATE" class="id_link">#</a></dt><dd><p>
728 An invalid token in the input string was found by the
729 <code class="function">PGTYPESdate_defmt_asc</code> function.
730 </p></dd><dt id="ECPG-PGTYPES-ERRNO-PGTYPES-INTVL-BAD-INTERVAL"><span class="term"><code class="literal">PGTYPES_INTVL_BAD_INTERVAL</code></span> <a href="#ECPG-PGTYPES-ERRNO-PGTYPES-INTVL-BAD-INTERVAL" class="id_link">#</a></dt><dd><p>
731 An invalid interval string was passed to the
732 <code class="function">PGTYPESinterval_from_asc</code> function, or an
733 invalid interval value was passed to the
734 <code class="function">PGTYPESinterval_to_asc</code> function.
735 </p></dd><dt id="ECPG-PGTYPES-ERRNO-PGTYPES-DATE-ERR-ENOTDMY"><span class="term"><code class="literal">PGTYPES_DATE_ERR_ENOTDMY</code></span> <a href="#ECPG-PGTYPES-ERRNO-PGTYPES-DATE-ERR-ENOTDMY" class="id_link">#</a></dt><dd><p>
736 There was a mismatch in the day/month/year assignment in the
737 <code class="function">PGTYPESdate_defmt_asc</code> function.
738 </p></dd><dt id="ECPG-PGTYPES-ERRNO-PGTYPES-DATE-BAD-DAY"><span class="term"><code class="literal">PGTYPES_DATE_BAD_DAY</code></span> <a href="#ECPG-PGTYPES-ERRNO-PGTYPES-DATE-BAD-DAY" class="id_link">#</a></dt><dd><p>
739 An invalid day of the month value was found by
740 the <code class="function">PGTYPESdate_defmt_asc</code> function.
741 </p></dd><dt id="ECPG-PGTYPES-ERRNO-PGTYPES-DATE-BAD-MONTH"><span class="term"><code class="literal">PGTYPES_DATE_BAD_MONTH</code></span> <a href="#ECPG-PGTYPES-ERRNO-PGTYPES-DATE-BAD-MONTH" class="id_link">#</a></dt><dd><p>
742 An invalid month value was found by
743 the <code class="function">PGTYPESdate_defmt_asc</code> function.
744 </p></dd><dt id="ECPG-PGTYPES-ERRNO-PGTYPES-TS-BAD-TIMESTAMP"><span class="term"><code class="literal">PGTYPES_TS_BAD_TIMESTAMP</code></span> <a href="#ECPG-PGTYPES-ERRNO-PGTYPES-TS-BAD-TIMESTAMP" class="id_link">#</a></dt><dd><p>
745 An invalid timestamp string pass passed to
746 the <code class="function">PGTYPEStimestamp_from_asc</code> function,
747 or an invalid timestamp value was passed to
748 the <code class="function">PGTYPEStimestamp_to_asc</code> function.
749 </p></dd><dt id="ECPG-PGTYPES-ERRNO-PGTYPES-TS-ERR-EINFTIME"><span class="term"><code class="literal">PGTYPES_TS_ERR_EINFTIME</code></span> <a href="#ECPG-PGTYPES-ERRNO-PGTYPES-TS-ERR-EINFTIME" class="id_link">#</a></dt><dd><p>
750 An infinite timestamp value was encountered in a context that
752 </p></dd></dl></div><p>
753 </p></div><div class="sect2" id="ECPG-PGTYPES-CONSTANTS"><div class="titlepage"><div><div><h3 class="title">34.6.8. Special Constants of pgtypeslib <a href="#ECPG-PGTYPES-CONSTANTS" class="id_link">#</a></h3></div></div></div><p>
754 </p><div class="variablelist"><dl class="variablelist"><dt id="PGTYPESINVALIDTIMESTAMP"><span class="term"><code class="literal">PGTYPESInvalidTimestamp</code></span> <a href="#PGTYPESINVALIDTIMESTAMP" class="id_link">#</a></dt><dd><p>
755 A value of type timestamp representing an invalid time stamp. This is
756 returned by the function <code class="function">PGTYPEStimestamp_from_asc</code> on
758 Note that due to the internal representation of the <code class="type">timestamp</code> data type,
759 <code class="literal">PGTYPESInvalidTimestamp</code> is also a valid timestamp at
760 the same time. It is set to <code class="literal">1899-12-31 23:59:59</code>. In order
761 to detect errors, make sure that your application does not only test
762 for <code class="literal">PGTYPESInvalidTimestamp</code> but also for
763 <code class="literal">errno != 0</code> after each call to
764 <code class="function">PGTYPEStimestamp_from_asc</code>.
765 </p></dd></dl></div><p>
766 </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-dynamic.html" title="34.5. Dynamic SQL">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg.html" title="Chapter 34. ECPG — Embedded SQL in C">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-descriptors.html" title="34.7. Using Descriptor Areas">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.5. Dynamic SQL </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.7. Using Descriptor Areas</td></tr></table></div></body></html>
begriffs.com / projects / ai-pg / blob