begriffs open source - ai-pg/blob - full-docs/src/sgml/html/ecpg-informix-compat.html

   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.15. Informix Compatibility Mode</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-sql-whenever.html" title="WHENEVER" /><link rel="next" href="ecpg-oracle-compat.html" title="34.16. Oracle Compatibility Mode" /></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.15. <span class="productname">Informix</span> Compatibility Mode</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-sql-whenever.html" title="WHENEVER">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-oracle-compat.html" title="34.16. Oracle Compatibility Mode">Next</a></td></tr></table><hr /></div><div class="sect1" id="ECPG-INFORMIX-COMPAT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.15. <span class="productname">Informix</span> Compatibility Mode <a href="#ECPG-INFORMIX-COMPAT" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ecpg-informix-compat.html#ECPG-INFORMIX-TYPES">34.15.1. Additional Types</a></span></dt><dt><span class="sect2"><a href="ecpg-informix-compat.html#ECPG-INFORMIX-STATEMENTS">34.15.2. Additional/Missing Embedded SQL Statements</a></span></dt><dt><span class="sect2"><a href="ecpg-informix-compat.html#ECPG-INFORMIX-SQLDA">34.15.3. Informix-compatible SQLDA Descriptor Areas</a></span></dt><dt><span class="sect2"><a href="ecpg-informix-compat.html#ECPG-INFORMIX-FUNCTIONS">34.15.4. Additional Functions</a></span></dt><dt><span class="sect2"><a href="ecpg-informix-compat.html#ECPG-INFORMIX-CONSTANTS">34.15.5. Additional Constants</a></span></dt></dl></div><p>
   3    <code class="command">ecpg</code> can be run in a so-called <em class="firstterm">Informix compatibility mode</em>. If
   4    this mode is active, it tries to behave as if it were the <span class="productname">Informix</span>
   5    precompiler for <span class="productname">Informix</span> E/SQL. Generally spoken this will allow you to use
   6    the dollar sign instead of the <code class="literal">EXEC SQL</code> primitive to introduce
   7    embedded SQL commands:
   8 </p><pre class="programlisting">
   9 $int j = 3;
  10 $CONNECT TO :dbname;
  11 $CREATE TABLE test(i INT PRIMARY KEY, j INT);
  12 $INSERT INTO test(i, j) VALUES (7, :j);
  13 $COMMIT;
  14 </pre><p>
  15   </p><div class="note"><h3 class="title">Note</h3><p>
  16     There must not be any white space between the <code class="literal">$</code>
  17     and a following preprocessor directive, that is,
  18     <code class="literal">include</code>, <code class="literal">define</code>, <code class="literal">ifdef</code>,
  19     etc.  Otherwise, the preprocessor will parse the token as a host
  20     variable.
  21    </p></div><p>
  22    There are two compatibility modes: <code class="literal">INFORMIX</code>, <code class="literal">INFORMIX_SE</code>
  23   </p><p>
  24    When linking programs that use this compatibility mode, remember to link
  25    against <code class="literal">libcompat</code> that is shipped with ECPG.
  26   </p><p>
  27    Besides the previously explained syntactic sugar, the <span class="productname">Informix</span> compatibility
  28    mode ports some functions for input, output and transformation of data as
  29    well as embedded SQL statements known from E/SQL to ECPG.
  30   </p><p>
  31    <span class="productname">Informix</span> compatibility mode is closely connected to the pgtypeslib library
  32    of ECPG. pgtypeslib maps SQL data types to data types within the C host
  33    program and most of the additional functions of the <span class="productname">Informix</span> compatibility
  34    mode allow you to operate on those C host program types. Note however that
  35    the extent of the compatibility is limited. It does not try to copy <span class="productname">Informix</span>
  36    behavior; it allows you to do more or less the same operations and gives
  37    you functions that have the same name and the same basic behavior but it is
  38    no drop-in replacement if you are using <span class="productname">Informix</span> at the moment. Moreover,
  39    some of the data types are different. For example,
  40    <span class="productname">PostgreSQL</span>'s datetime and interval types do not
  41    know about ranges like for example <code class="literal">YEAR TO MINUTE</code> so you won't
  42    find support in ECPG for that either.
  43   </p><div class="sect2" id="ECPG-INFORMIX-TYPES"><div class="titlepage"><div><div><h3 class="title">34.15.1. Additional Types <a href="#ECPG-INFORMIX-TYPES" class="id_link">#</a></h3></div></div></div><p>
  44     The Informix-special "string" pseudo-type for storing right-trimmed character string data is now
  45     supported in Informix-mode without using <code class="literal">typedef</code>. In fact, in Informix-mode,
  46     ECPG refuses to process source files that contain <code class="literal">typedef sometype string;</code>
  47 </p><pre class="programlisting">
  48 EXEC SQL BEGIN DECLARE SECTION;
  49 string userid; /* this variable will contain trimmed data */
  50 EXEC SQL END DECLARE SECTION;
  51
  52 EXEC SQL FETCH MYCUR INTO :userid;
  53 </pre><p>
  54    </p></div><div class="sect2" id="ECPG-INFORMIX-STATEMENTS"><div class="titlepage"><div><div><h3 class="title">34.15.2. Additional/Missing Embedded SQL Statements <a href="#ECPG-INFORMIX-STATEMENTS" class="id_link">#</a></h3></div></div></div><p>
  55     </p><div class="variablelist"><dl class="variablelist"><dt id="ECPG-INFORMIX-STATEMENTS-CLOSE-DATABASE"><span class="term"><code class="literal">CLOSE DATABASE</code></span> <a href="#ECPG-INFORMIX-STATEMENTS-CLOSE-DATABASE" class="id_link">#</a></dt><dd><p>
  56         This statement closes the current connection. In fact, this is a
  57         synonym for ECPG's <code class="literal">DISCONNECT CURRENT</code>:
  58 </p><pre class="programlisting">
  59 $CLOSE DATABASE;                /* close the current connection */
  60 EXEC SQL CLOSE DATABASE;
  61 </pre><p>
  62        </p></dd><dt id="ECPG-INFORMIX-STATEMENTS-FREE-CURSOR-NAME"><span class="term"><code class="literal">FREE cursor_name</code></span> <a href="#ECPG-INFORMIX-STATEMENTS-FREE-CURSOR-NAME" class="id_link">#</a></dt><dd><p>
  63         Due to differences in how ECPG works compared to Informix's ESQL/C (namely, which steps
  64         are purely grammar transformations and which steps rely on the underlying run-time library)
  65         there is no <code class="literal">FREE cursor_name</code> statement in ECPG. This is because in ECPG,
  66         <code class="literal">DECLARE CURSOR</code> doesn't translate to a function call into
  67         the run-time library that uses to the cursor name. This means that there's no run-time
  68         bookkeeping of SQL cursors in the ECPG run-time library, only in the PostgreSQL server.
  69        </p></dd><dt id="ECPG-INFORMIX-STATEMENTS-FREE-STATEMENT-NAME"><span class="term"><code class="literal">FREE statement_name</code></span> <a href="#ECPG-INFORMIX-STATEMENTS-FREE-STATEMENT-NAME" class="id_link">#</a></dt><dd><p>
  70         <code class="literal">FREE statement_name</code> is a synonym for <code class="literal">DEALLOCATE PREPARE statement_name</code>.
  71        </p></dd></dl></div><p>
  72    </p></div><div class="sect2" id="ECPG-INFORMIX-SQLDA"><div class="titlepage"><div><div><h3 class="title">34.15.3. Informix-compatible SQLDA Descriptor Areas <a href="#ECPG-INFORMIX-SQLDA" class="id_link">#</a></h3></div></div></div><p>
  73     Informix-compatible mode supports a different structure than the one described in
  74     <a class="xref" href="ecpg-descriptors.html#ECPG-SQLDA-DESCRIPTORS" title="34.7.2. SQLDA Descriptor Areas">Section 34.7.2</a>. See below:
  75 </p><pre class="programlisting">
  76 struct sqlvar_compat
  77 {
  78     short   sqltype;
  79     int     sqllen;
  80     char   *sqldata;
  81     short  *sqlind;
  82     char   *sqlname;
  83     char   *sqlformat;
  84     short   sqlitype;
  85     short   sqlilen;
  86     char   *sqlidata;
  87     int     sqlxid;
  88     char   *sqltypename;
  89     short   sqltypelen;
  90     short   sqlownerlen;
  91     short   sqlsourcetype;
  92     char   *sqlownername;
  93     int     sqlsourceid;
  94     char   *sqlilongdata;
  95     int     sqlflags;
  96     void   *sqlreserved;
  97 };
  98
  99 struct sqlda_compat
 100 {
 101     short  sqld;
 102     struct sqlvar_compat *sqlvar;
 103     char   desc_name[19];
 104     short  desc_occ;
 105     struct sqlda_compat *desc_next;
 106     void  *reserved;
 107 };
 108
 109 typedef struct sqlvar_compat    sqlvar_t;
 110 typedef struct sqlda_compat     sqlda_t;
 111 </pre><p>
 112    </p><p>
 113     The global properties are:
 114     </p><div class="variablelist"><dl class="variablelist"><dt id="ECPG-INFORMIX-SQLDA-SQLD"><span class="term"><code class="literal">sqld</code></span> <a href="#ECPG-INFORMIX-SQLDA-SQLD" class="id_link">#</a></dt><dd><p>
 115         The number of fields in the <code class="literal">SQLDA</code> descriptor.
 116        </p></dd><dt id="ECPG-INFORMIX-SQLDA-SQLVAR"><span class="term"><code class="literal">sqlvar</code></span> <a href="#ECPG-INFORMIX-SQLDA-SQLVAR" class="id_link">#</a></dt><dd><p>
 117         Pointer to the per-field properties.
 118        </p></dd><dt id="ECPG-INFORMIX-SQLDA-DESC-NAME"><span class="term"><code class="literal">desc_name</code></span> <a href="#ECPG-INFORMIX-SQLDA-DESC-NAME" class="id_link">#</a></dt><dd><p>
 119         Unused, filled with zero-bytes.
 120        </p></dd><dt id="ECPG-INFORMIX-SQLDA-DESC-OCC"><span class="term"><code class="literal">desc_occ</code></span> <a href="#ECPG-INFORMIX-SQLDA-DESC-OCC" class="id_link">#</a></dt><dd><p>
 121         Size of the allocated structure.
 122        </p></dd><dt id="ECPG-INFORMIX-SQLDA-DESC-NEXT"><span class="term"><code class="literal">desc_next</code></span> <a href="#ECPG-INFORMIX-SQLDA-DESC-NEXT" class="id_link">#</a></dt><dd><p>
 123         Pointer to the next SQLDA structure if the result set contains more than one record.
 124        </p></dd><dt id="ECPG-INFORMIX-SQLDA-RESERVED"><span class="term"><code class="literal">reserved</code></span> <a href="#ECPG-INFORMIX-SQLDA-RESERVED" class="id_link">#</a></dt><dd><p>
 125         Unused pointer, contains NULL. Kept for Informix-compatibility.
 126        </p></dd></dl></div><p>
 127
 128     The per-field properties are below, they are stored in the <code class="literal">sqlvar</code> array:
 129
 130     </p><div class="variablelist"><dl class="variablelist"><dt id="ECPG-INFORMIX-SQLDA-SQLTYPE"><span class="term"><code class="literal">sqltype</code></span> <a href="#ECPG-INFORMIX-SQLDA-SQLTYPE" class="id_link">#</a></dt><dd><p>
 131         Type of the field. Constants are in <code class="literal">sqltypes.h</code>
 132        </p></dd><dt id="ECPG-INFORMIX-SQLDA-SQLLEN"><span class="term"><code class="literal">sqllen</code></span> <a href="#ECPG-INFORMIX-SQLDA-SQLLEN" class="id_link">#</a></dt><dd><p>
 133         Length of the field data.
 134        </p></dd><dt id="ECPG-INFORMIX-SQLDA-SQLDATA"><span class="term"><code class="literal">sqldata</code></span> <a href="#ECPG-INFORMIX-SQLDA-SQLDATA" class="id_link">#</a></dt><dd><p>
 135         Pointer to the field data. The pointer is of <code class="literal">char *</code> type,
 136         the data pointed by it is in a binary format. Example:
 137 </p><pre class="programlisting">
 138 int intval;
 139
 140 switch (sqldata-&gt;sqlvar[i].sqltype)
 141 {
 142     case SQLINTEGER:
 143         intval = *(int *)sqldata-&gt;sqlvar[i].sqldata;
 144         break;
 145   ...
 146 }
 147 </pre><p>
 148        </p></dd><dt id="ECPG-INFORMIX-SQLDA-SQLIND"><span class="term"><code class="literal">sqlind</code></span> <a href="#ECPG-INFORMIX-SQLDA-SQLIND" class="id_link">#</a></dt><dd><p>
 149         Pointer to the NULL indicator. If returned by DESCRIBE or FETCH then it's always a valid pointer.
 150         If used as input for <code class="literal">EXECUTE ... USING sqlda;</code> then NULL-pointer value means
 151         that the value for this field is non-NULL. Otherwise a valid pointer and <code class="literal">sqlitype</code>
 152         has to be properly set. Example:
 153 </p><pre class="programlisting">
 154 if (*(int2 *)sqldata-&gt;sqlvar[i].sqlind != 0)
 155     printf("value is NULL\n");
 156 </pre><p>
 157        </p></dd><dt id="ECPG-INFORMIX-SQLDA-SQLNAME"><span class="term"><code class="literal">sqlname</code></span> <a href="#ECPG-INFORMIX-SQLDA-SQLNAME" class="id_link">#</a></dt><dd><p>
 158         Name of the field. 0-terminated string.
 159        </p></dd><dt id="ECPG-INFORMIX-SQLDA-SQLFORMAT"><span class="term"><code class="literal">sqlformat</code></span> <a href="#ECPG-INFORMIX-SQLDA-SQLFORMAT" class="id_link">#</a></dt><dd><p>
 160         Reserved in Informix, value of <a class="xref" href="libpq-exec.html#LIBPQ-PQFFORMAT"><code class="function">PQfformat</code></a> for the field.
 161        </p></dd><dt id="ECPG-INFORMIX-SQLDA-SQLITYPE"><span class="term"><code class="literal">sqlitype</code></span> <a href="#ECPG-INFORMIX-SQLDA-SQLITYPE" class="id_link">#</a></dt><dd><p>
 162         Type of the NULL indicator data. It's always SQLSMINT when returning data from the server.
 163         When the <code class="literal">SQLDA</code> is used for a parameterized query, the data is treated
 164         according to the set type.
 165        </p></dd><dt id="ECPG-INFORMIX-SQLDA-SQLILEN"><span class="term"><code class="literal">sqlilen</code></span> <a href="#ECPG-INFORMIX-SQLDA-SQLILEN" class="id_link">#</a></dt><dd><p>
 166         Length of the NULL indicator data.
 167        </p></dd><dt id="ECPG-INFORMIX-SQLDA-SQLXID"><span class="term"><code class="literal">sqlxid</code></span> <a href="#ECPG-INFORMIX-SQLDA-SQLXID" class="id_link">#</a></dt><dd><p>
 168         Extended type of the field, result of <a class="xref" href="libpq-exec.html#LIBPQ-PQFTYPE"><code class="function">PQftype</code></a>.
 169        </p></dd><dt id="ECPG-INFORMIX-SQLDA-SQLTYPENAME"><span class="term"><code class="literal">sqltypename</code><br /></span><span class="term"><code class="literal">sqltypelen</code><br /></span><span class="term"><code class="literal">sqlownerlen</code><br /></span><span class="term"><code class="literal">sqlsourcetype</code><br /></span><span class="term"><code class="literal">sqlownername</code><br /></span><span class="term"><code class="literal">sqlsourceid</code><br /></span><span class="term"><code class="literal">sqlflags</code><br /></span><span class="term"><code class="literal">sqlreserved</code></span> <a href="#ECPG-INFORMIX-SQLDA-SQLTYPENAME" class="id_link">#</a></dt><dd><p>
 170         Unused.
 171        </p></dd><dt id="ECPG-INFORMIX-SQLDA-SQLILONGDATA"><span class="term"><code class="literal">sqlilongdata</code></span> <a href="#ECPG-INFORMIX-SQLDA-SQLILONGDATA" class="id_link">#</a></dt><dd><p>
 172         It equals to <code class="literal">sqldata</code> if <code class="literal">sqllen</code> is larger than 32kB.
 173        </p></dd></dl></div><p>
 174
 175     Example:
 176 </p><pre class="programlisting">
 177 EXEC SQL INCLUDE sqlda.h;
 178
 179     sqlda_t        *sqlda; /* This doesn't need to be under embedded DECLARE SECTION */
 180
 181     EXEC SQL BEGIN DECLARE SECTION;
 182     char *prep_stmt = "select * from table1";
 183     int i;
 184     EXEC SQL END DECLARE SECTION;
 185
 186     ...
 187
 188     EXEC SQL PREPARE mystmt FROM :prep_stmt;
 189
 190     EXEC SQL DESCRIBE mystmt INTO sqlda;
 191
 192     printf("# of fields: %d\n", sqlda-&gt;sqld);
 193     for (i = 0; i &lt; sqlda-&gt;sqld; i++)
 194       printf("field %d: \"%s\"\n", sqlda-&gt;sqlvar[i]-&gt;sqlname);
 195
 196     EXEC SQL DECLARE mycursor CURSOR FOR mystmt;
 197     EXEC SQL OPEN mycursor;
 198     EXEC SQL WHENEVER NOT FOUND GOTO out;
 199
 200     while (1)
 201     {
 202       EXEC SQL FETCH mycursor USING sqlda;
 203     }
 204
 205     EXEC SQL CLOSE mycursor;
 206
 207     free(sqlda); /* The main structure is all to be free(),
 208                   * sqlda and sqlda-&gt;sqlvar is in one allocated area */
 209 </pre><p>
 210     For more information, see the <code class="literal">sqlda.h</code> header and the
 211     <code class="literal">src/interfaces/ecpg/test/compat_informix/sqlda.pgc</code> regression test.
 212    </p></div><div class="sect2" id="ECPG-INFORMIX-FUNCTIONS"><div class="titlepage"><div><div><h3 class="title">34.15.4. Additional Functions <a href="#ECPG-INFORMIX-FUNCTIONS" class="id_link">#</a></h3></div></div></div><p>
 213     </p><div class="variablelist"><dl class="variablelist"><dt id="ECPG-INFORMIX-FUNCTIONS-DECADD"><span class="term"><code class="function">decadd</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-DECADD" class="id_link">#</a></dt><dd><p>
 214         Add two decimal type values.
 215 </p><pre class="synopsis">
 216 int decadd(decimal *arg1, decimal *arg2, decimal *sum);
 217 </pre><p>
 218         The function receives a pointer to the first operand of type decimal
 219         (<code class="literal">arg1</code>), a pointer to the second operand of type decimal
 220         (<code class="literal">arg2</code>) and a pointer to a value of type decimal that will
 221         contain the sum (<code class="literal">sum</code>). On success, the function returns 0.
 222         <code class="symbol">ECPG_INFORMIX_NUM_OVERFLOW</code> is returned in case of overflow and
 223         <code class="symbol">ECPG_INFORMIX_NUM_UNDERFLOW</code> in case of underflow. -1 is returned for
 224         other failures and <code class="varname">errno</code> is set to the respective <code class="varname">errno</code> number of the
 225         pgtypeslib.
 226        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-DECCMP"><span class="term"><code class="function">deccmp</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-DECCMP" class="id_link">#</a></dt><dd><p>
 227         Compare two variables of type decimal.
 228 </p><pre class="synopsis">
 229 int deccmp(decimal *arg1, decimal *arg2);
 230 </pre><p>
 231         The function receives a pointer to the first decimal value
 232         (<code class="literal">arg1</code>), a pointer to the second decimal value
 233         (<code class="literal">arg2</code>) and returns an integer value that indicates which is
 234         the bigger value.
 235         </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
 236            1, if the value that <code class="literal">arg1</code> points to is bigger than the
 237            value that <code class="literal">var2</code> points to
 238           </p></li><li class="listitem"><p>
 239            -1, if the value that <code class="literal">arg1</code> points to is smaller than the
 240            value that <code class="literal">arg2</code> points to </p></li><li class="listitem"><p>
 241            0, if the value that <code class="literal">arg1</code> points to and the value that
 242            <code class="literal">arg2</code> points to are equal
 243           </p></li></ul></div><p>
 244        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-DECCOPY"><span class="term"><code class="function">deccopy</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-DECCOPY" class="id_link">#</a></dt><dd><p>
 245         Copy a decimal value.
 246 </p><pre class="synopsis">
 247 void deccopy(decimal *src, decimal *target);
 248 </pre><p>
 249         The function receives a pointer to the decimal value that should be
 250         copied as the first argument (<code class="literal">src</code>) and a pointer to the
 251         target structure of type decimal (<code class="literal">target</code>) as the second
 252         argument.
 253        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-DECCVASC"><span class="term"><code class="function">deccvasc</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-DECCVASC" class="id_link">#</a></dt><dd><p>
 254         Convert a value from its ASCII representation into a decimal type.
 255 </p><pre class="synopsis">
 256 int deccvasc(char *cp, int len, decimal *np);
 257 </pre><p>
 258         The function receives a pointer to string that contains the string
 259         representation of the number to be converted (<code class="literal">cp</code>) as well
 260         as its length <code class="literal">len</code>. <code class="literal">np</code> is a pointer to the
 261         decimal value that saves the result of the operation.
 262        </p><p>
 263         Valid formats are for example:
 264          <code class="literal">-2</code>,
 265          <code class="literal">.794</code>,
 266          <code class="literal">+3.44</code>,
 267          <code class="literal">592.49E07</code> or
 268          <code class="literal">-32.84e-4</code>.
 269        </p><p>
 270         The function returns 0 on success. If overflow or underflow occurred,
 271         <code class="literal">ECPG_INFORMIX_NUM_OVERFLOW</code> or
 272         <code class="literal">ECPG_INFORMIX_NUM_UNDERFLOW</code> is returned. If the ASCII
 273         representation could not be parsed,
 274         <code class="literal">ECPG_INFORMIX_BAD_NUMERIC</code> is returned or
 275         <code class="literal">ECPG_INFORMIX_BAD_EXPONENT</code> if this problem occurred while
 276         parsing the exponent.
 277        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-DECCVDBL"><span class="term"><code class="function">deccvdbl</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-DECCVDBL" class="id_link">#</a></dt><dd><p>
 278         Convert a value of type double to a value of type decimal.
 279 </p><pre class="synopsis">
 280 int deccvdbl(double dbl, decimal *np);
 281 </pre><p>
 282         The function receives the variable of type double that should be
 283         converted as its first argument (<code class="literal">dbl</code>). As the second
 284         argument (<code class="literal">np</code>), the function receives a pointer to the
 285         decimal variable that should hold the result of the operation.
 286        </p><p>
 287         The function returns 0 on success and a negative value if the
 288         conversion failed.
 289        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-DECCVINT"><span class="term"><code class="function">deccvint</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-DECCVINT" class="id_link">#</a></dt><dd><p>
 290         Convert a value of type int to a value of type decimal.
 291 </p><pre class="synopsis">
 292 int deccvint(int in, decimal *np);
 293 </pre><p>
 294         The function receives the variable of type int that should be
 295         converted as its first argument (<code class="literal">in</code>). As the second
 296         argument (<code class="literal">np</code>), the function receives a pointer to the
 297         decimal variable that should hold the result of the operation.
 298        </p><p>
 299         The function returns 0 on success and a negative value if the
 300         conversion failed.
 301        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-DECCVLONG"><span class="term"><code class="function">deccvlong</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-DECCVLONG" class="id_link">#</a></dt><dd><p>
 302         Convert a value of type long to a value of type decimal.
 303 </p><pre class="synopsis">
 304 int deccvlong(long lng, decimal *np);
 305 </pre><p>
 306         The function receives the variable of type long that should be
 307         converted as its first argument (<code class="literal">lng</code>). As the second
 308         argument (<code class="literal">np</code>), the function receives a pointer to the
 309         decimal variable that should hold the result of the operation.
 310        </p><p>
 311         The function returns 0 on success and a negative value if the
 312         conversion failed.
 313        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-DECDIV"><span class="term"><code class="function">decdiv</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-DECDIV" class="id_link">#</a></dt><dd><p>
 314         Divide two variables of type decimal.
 315 </p><pre class="synopsis">
 316 int decdiv(decimal *n1, decimal *n2, decimal *result);
 317 </pre><p>
 318         The function receives pointers to the variables that are the first
 319         (<code class="literal">n1</code>) and the second (<code class="literal">n2</code>) operands and
 320         calculates <code class="literal">n1</code>/<code class="literal">n2</code>. <code class="literal">result</code> is a
 321         pointer to the variable that should hold the result of the operation.
 322        </p><p>
 323         On success, 0 is returned and a negative value if the division fails.
 324         If overflow or underflow occurred, the function returns
 325         <code class="literal">ECPG_INFORMIX_NUM_OVERFLOW</code> or
 326         <code class="literal">ECPG_INFORMIX_NUM_UNDERFLOW</code> respectively. If an attempt to
 327         divide by zero is observed, the function returns
 328         <code class="literal">ECPG_INFORMIX_DIVIDE_ZERO</code>.
 329        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-DECMUL"><span class="term"><code class="function">decmul</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-DECMUL" class="id_link">#</a></dt><dd><p>
 330         Multiply two decimal values.
 331 </p><pre class="synopsis">
 332 int decmul(decimal *n1, decimal *n2, decimal *result);
 333 </pre><p>
 334         The function receives pointers to the variables that are the first
 335         (<code class="literal">n1</code>) and the second (<code class="literal">n2</code>) operands and
 336         calculates <code class="literal">n1</code>*<code class="literal">n2</code>. <code class="literal">result</code> is a
 337         pointer to the variable that should hold the result of the operation.
 338        </p><p>
 339         On success, 0 is returned and a negative value if the multiplication
 340         fails. If overflow or underflow occurred, the function returns
 341         <code class="literal">ECPG_INFORMIX_NUM_OVERFLOW</code> or
 342         <code class="literal">ECPG_INFORMIX_NUM_UNDERFLOW</code> respectively.
 343        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-DECSUB"><span class="term"><code class="function">decsub</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-DECSUB" class="id_link">#</a></dt><dd><p>
 344         Subtract one decimal value from another.
 345 </p><pre class="synopsis">
 346 int decsub(decimal *n1, decimal *n2, decimal *result);
 347 </pre><p>
 348         The function receives pointers to the variables that are the first
 349         (<code class="literal">n1</code>) and the second (<code class="literal">n2</code>) operands and
 350         calculates <code class="literal">n1</code>-<code class="literal">n2</code>. <code class="literal">result</code> is a
 351         pointer to the variable that should hold the result of the operation.
 352        </p><p>
 353         On success, 0 is returned and a negative value if the subtraction
 354         fails. If overflow or underflow occurred, the function returns
 355         <code class="literal">ECPG_INFORMIX_NUM_OVERFLOW</code> or
 356         <code class="literal">ECPG_INFORMIX_NUM_UNDERFLOW</code> respectively.
 357        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-DECTOASC"><span class="term"><code class="function">dectoasc</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-DECTOASC" class="id_link">#</a></dt><dd><p>
 358         Convert a variable of type decimal to its ASCII representation in a C
 359         char* string.
 360 </p><pre class="synopsis">
 361 int dectoasc(decimal *np, char *cp, int len, int right)
 362 </pre><p>
 363         The function receives a pointer to a variable of type decimal
 364         (<code class="literal">np</code>) that it converts to its textual representation.
 365         <code class="literal">cp</code> is the buffer that should hold the result of the
 366         operation. The parameter <code class="literal">right</code> specifies, how many digits
 367         right of the decimal point should be included in the output. The result
 368         will be rounded to this number of decimal digits. Setting
 369         <code class="literal">right</code> to -1 indicates that all available decimal digits
 370         should be included in the output. If the length of the output buffer,
 371         which is indicated by <code class="literal">len</code> is not sufficient to hold the
 372         textual representation including the trailing zero byte, only a
 373         single <code class="literal">*</code> character is stored in the result and -1 is
 374         returned.
 375        </p><p>
 376         The function returns either -1 if the buffer <code class="literal">cp</code> was too
 377         small or <code class="literal">ECPG_INFORMIX_OUT_OF_MEMORY</code> if memory was
 378         exhausted.
 379        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-DECTODBL"><span class="term"><code class="function">dectodbl</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-DECTODBL" class="id_link">#</a></dt><dd><p>
 380         Convert a variable of type decimal to a double.
 381 </p><pre class="synopsis">
 382 int dectodbl(decimal *np, double *dblp);
 383 </pre><p>
 384         The function receives a pointer to the decimal value to convert
 385         (<code class="literal">np</code>) and a pointer to the double variable that
 386         should hold the result of the operation (<code class="literal">dblp</code>).
 387        </p><p>
 388         On success, 0 is returned and a negative value if the conversion
 389         failed.
 390        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-DECTOINT"><span class="term"><code class="function">dectoint</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-DECTOINT" class="id_link">#</a></dt><dd><p>
 391         Convert a variable of type decimal to an integer.
 392 </p><pre class="synopsis">
 393 int dectoint(decimal *np, int *ip);
 394 </pre><p>
 395         The function receives a pointer to the decimal value to convert
 396         (<code class="literal">np</code>) and a pointer to the integer variable that
 397         should hold the result of the operation (<code class="literal">ip</code>).
 398        </p><p>
 399         On success, 0 is returned and a negative value if the conversion
 400         failed. If an overflow occurred, <code class="literal">ECPG_INFORMIX_NUM_OVERFLOW</code>
 401         is returned.
 402        </p><p>
 403         Note that the ECPG implementation differs from the <span class="productname">Informix</span>
 404         implementation. <span class="productname">Informix</span> limits an integer to the range from -32767 to
 405         32767, while the limits in the ECPG implementation depend on the
 406         architecture (<code class="literal">INT_MIN .. INT_MAX</code>).
 407        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-DECTOLONG"><span class="term"><code class="function">dectolong</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-DECTOLONG" class="id_link">#</a></dt><dd><p>
 408         Convert a variable of type decimal to a long integer.
 409 </p><pre class="synopsis">
 410 int dectolong(decimal *np, long *lngp);
 411 </pre><p>
 412         The function receives a pointer to the decimal value to convert
 413         (<code class="literal">np</code>) and a pointer to the long variable that
 414         should hold the result of the operation (<code class="literal">lngp</code>).
 415        </p><p>
 416         On success, 0 is returned and a negative value if the conversion
 417         failed. If an overflow occurred, <code class="literal">ECPG_INFORMIX_NUM_OVERFLOW</code>
 418         is returned.
 419        </p><p>
 420         Note that the ECPG implementation differs from the <span class="productname">Informix</span>
 421         implementation. <span class="productname">Informix</span> limits a long integer to the range from
 422         -2,147,483,647 to 2,147,483,647, while the limits in the ECPG
 423         implementation depend on the architecture (<code class="literal">-LONG_MAX ..
 424         LONG_MAX</code>).
 425        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-RDATESTR"><span class="term"><code class="function">rdatestr</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-RDATESTR" class="id_link">#</a></dt><dd><p>
 426         Converts a date to a C char* string.
 427 </p><pre class="synopsis">
 428 int rdatestr(date d, char *str);
 429 </pre><p>
 430         The function receives two arguments, the first one is the date to
 431         convert (<code class="literal">d</code>) and the second one is a pointer to the target
 432         string. The output format is always <code class="literal">yyyy-mm-dd</code>, so you need
 433         to allocate at least 11 bytes (including the zero-byte terminator) for the
 434         string.
 435        </p><p>
 436         The function returns 0 on success and a negative value in case of
 437         error.
 438        </p><p>
 439         Note that ECPG's implementation differs from the <span class="productname">Informix</span>
 440         implementation. In <span class="productname">Informix</span> the format can be influenced by setting
 441         environment variables. In ECPG however, you cannot change the output
 442         format.
 443        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-RSTRDATE"><span class="term"><code class="function">rstrdate</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-RSTRDATE" class="id_link">#</a></dt><dd><p>
 444         Parse the textual representation of a date.
 445 </p><pre class="synopsis">
 446 int rstrdate(char *str, date *d);
 447 </pre><p>
 448         The function receives the textual representation of the date to convert
 449         (<code class="literal">str</code>) and a pointer to a variable of type date
 450         (<code class="literal">d</code>). This function does not allow you to specify a format
 451         mask. It uses the default format mask of <span class="productname">Informix</span> which is
 452         <code class="literal">mm/dd/yyyy</code>. Internally, this function is implemented by
 453         means of <code class="function">rdefmtdate</code>. Therefore, <code class="function">rstrdate</code> is
 454         not faster and if you have the choice you should opt for
 455         <code class="function">rdefmtdate</code> which allows you to specify the format mask
 456         explicitly.
 457        </p><p>
 458         The function returns the same values as <code class="function">rdefmtdate</code>.
 459        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-RTODAY"><span class="term"><code class="function">rtoday</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-RTODAY" class="id_link">#</a></dt><dd><p>
 460         Get the current date.
 461 </p><pre class="synopsis">
 462 void rtoday(date *d);
 463 </pre><p>
 464         The function receives a pointer to a date variable (<code class="literal">d</code>)
 465         that it sets to the current date.
 466        </p><p>
 467         Internally this function uses the <a class="xref" href="ecpg-pgtypes.html#PGTYPESDATETODAY"><code class="function">PGTYPESdate_today</code></a>
 468         function.
 469        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-RJULMDY"><span class="term"><code class="function">rjulmdy</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-RJULMDY" class="id_link">#</a></dt><dd><p>
 470         Extract the values for the day, the month and the year from a variable
 471         of type date.
 472 </p><pre class="synopsis">
 473 int rjulmdy(date d, short mdy[3]);
 474 </pre><p>
 475         The function receives the date <code class="literal">d</code> and a pointer to an array
 476         of 3 short integer values <code class="literal">mdy</code>. The variable name indicates
 477         the sequential order: <code class="literal">mdy[0]</code> will be set to contain the
 478         number of the month, <code class="literal">mdy[1]</code> will be set to the value of the
 479         day and <code class="literal">mdy[2]</code> will contain the year.
 480        </p><p>
 481         The function always returns 0 at the moment.
 482        </p><p>
 483         Internally the function uses the <a class="xref" href="ecpg-pgtypes.html#PGTYPESDATEJULMDY"><code class="function">PGTYPESdate_julmdy</code></a>
 484         function.
 485        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-RDEFMTDATE"><span class="term"><code class="function">rdefmtdate</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-RDEFMTDATE" class="id_link">#</a></dt><dd><p>
 486         Use a format mask to convert a character string to a value of type
 487         date.
 488 </p><pre class="synopsis">
 489 int rdefmtdate(date *d, char *fmt, char *str);
 490 </pre><p>
 491         The function receives a pointer to the date value that should hold the
 492         result of the operation (<code class="literal">d</code>), the format mask to use for
 493         parsing the date (<code class="literal">fmt</code>) and the C char* string containing
 494         the textual representation of the date (<code class="literal">str</code>). The textual
 495         representation is expected to match the format mask. However you do not
 496         need to have a 1:1 mapping of the string to the format mask. The
 497         function only analyzes the sequential order and looks for the literals
 498         <code class="literal">yy</code> or <code class="literal">yyyy</code> that indicate the
 499         position of the year, <code class="literal">mm</code> to indicate the position of
 500         the month and <code class="literal">dd</code> to indicate the position of the
 501         day.
 502        </p><p>
 503         The function returns the following values:
 504         </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
 505            0 - The function terminated successfully.
 506           </p></li><li class="listitem"><p>
 507            <code class="literal">ECPG_INFORMIX_ENOSHORTDATE</code> - The date does not contain
 508            delimiters between day, month and year. In this case the input
 509            string must be exactly 6 or 8 bytes long but isn't.
 510           </p></li><li class="listitem"><p>
 511            <code class="literal">ECPG_INFORMIX_ENOTDMY</code> - The format string did not
 512            correctly indicate the sequential order of year, month and day.
 513           </p></li><li class="listitem"><p>
 514            <code class="literal">ECPG_INFORMIX_BAD_DAY</code> - The input string does not
 515            contain a valid day.
 516           </p></li><li class="listitem"><p>
 517            <code class="literal">ECPG_INFORMIX_BAD_MONTH</code> - The input string does not
 518            contain a valid month.
 519           </p></li><li class="listitem"><p>
 520            <code class="literal">ECPG_INFORMIX_BAD_YEAR</code> - The input string does not
 521            contain a valid year.
 522           </p></li></ul></div><p>
 523        </p><p>
 524         Internally this function is implemented to use the <a class="xref" href="ecpg-pgtypes.html#PGTYPESDATEDEFMTASC"><code class="function">PGTYPESdate_defmt_asc</code></a> function. See the reference there for a
 525         table of example input.
 526        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-RFMTDATE"><span class="term"><code class="function">rfmtdate</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-RFMTDATE" class="id_link">#</a></dt><dd><p>
 527         Convert a variable of type date to its textual representation using a
 528         format mask.
 529 </p><pre class="synopsis">
 530 int rfmtdate(date d, char *fmt, char *str);
 531 </pre><p>
 532         The function receives the date to convert (<code class="literal">d</code>), the format
 533         mask (<code class="literal">fmt</code>) and the string that will hold the textual
 534         representation of the date (<code class="literal">str</code>).
 535        </p><p>
 536         On success, 0 is returned and a negative value if an error occurred.
 537        </p><p>
 538         Internally this function uses the <a class="xref" href="ecpg-pgtypes.html#PGTYPESDATEFMTASC"><code class="function">PGTYPESdate_fmt_asc</code></a>
 539         function, see the reference there for examples.
 540        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-RMDYJUL"><span class="term"><code class="function">rmdyjul</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-RMDYJUL" class="id_link">#</a></dt><dd><p>
 541         Create a date value from an array of 3 short integers that specify the
 542         day, the month and the year of the date.
 543 </p><pre class="synopsis">
 544 int rmdyjul(short mdy[3], date *d);
 545 </pre><p>
 546         The function receives the array of the 3 short integers
 547         (<code class="literal">mdy</code>) and a pointer to a variable of type date that should
 548         hold the result of the operation.
 549        </p><p>
 550         Currently the function returns always 0.
 551        </p><p>
 552         Internally the function is implemented to use the function <a class="xref" href="ecpg-pgtypes.html#PGTYPESDATEMDYJUL"><code class="function">PGTYPESdate_mdyjul</code></a>.
 553        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-RDAYOFWEEK"><span class="term"><code class="function">rdayofweek</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-RDAYOFWEEK" class="id_link">#</a></dt><dd><p>
 554         Return a number representing the day of the week for a date value.
 555 </p><pre class="synopsis">
 556 int rdayofweek(date d);
 557 </pre><p>
 558         The function receives the date variable <code class="literal">d</code> as its only
 559         argument and returns an integer that indicates the day of the week for
 560         this date.
 561         </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
 562            0 - Sunday
 563           </p></li><li class="listitem"><p>
 564            1 - Monday
 565           </p></li><li class="listitem"><p>
 566            2 - Tuesday
 567           </p></li><li class="listitem"><p>
 568            3 - Wednesday
 569           </p></li><li class="listitem"><p>
 570            4 - Thursday
 571           </p></li><li class="listitem"><p>
 572            5 - Friday
 573           </p></li><li class="listitem"><p>
 574            6 - Saturday
 575           </p></li></ul></div><p>
 576        </p><p>
 577         Internally the function is implemented to use the function <a class="xref" href="ecpg-pgtypes.html#PGTYPESDATEDAYOFWEEK"><code class="function">PGTYPESdate_dayofweek</code></a>.
 578        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-DTCURRENT"><span class="term"><code class="function">dtcurrent</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-DTCURRENT" class="id_link">#</a></dt><dd><p>
 579         Retrieve the current timestamp.
 580 </p><pre class="synopsis">
 581 void dtcurrent(timestamp *ts);
 582 </pre><p>
 583         The function retrieves the current timestamp and saves it into the
 584         timestamp variable that <code class="literal">ts</code> points to.
 585        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-DTCVASC"><span class="term"><code class="function">dtcvasc</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-DTCVASC" class="id_link">#</a></dt><dd><p>
 586         Parses a timestamp from its textual representation
 587         into a timestamp variable.
 588 </p><pre class="synopsis">
 589 int dtcvasc(char *str, timestamp *ts);
 590 </pre><p>
 591         The function receives the string to parse (<code class="literal">str</code>) and a
 592         pointer to the timestamp variable that should hold the result of the
 593         operation (<code class="literal">ts</code>).
 594        </p><p>
 595         The function returns 0 on success and a negative value in case of
 596         error.
 597        </p><p>
 598         Internally this function uses the <a class="xref" href="ecpg-pgtypes.html#PGTYPESTIMESTAMPFROMASC"><code class="function">PGTYPEStimestamp_from_asc</code></a> function. See the reference there
 599         for a table with example inputs.
 600        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-DTCVFMTASC"><span class="term"><code class="function">dtcvfmtasc</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-DTCVFMTASC" class="id_link">#</a></dt><dd><p>
 601         Parses a timestamp from its textual representation
 602         using a format mask into a timestamp variable.
 603 </p><pre class="synopsis">
 604 dtcvfmtasc(char *inbuf, char *fmtstr, timestamp *dtvalue)
 605 </pre><p>
 606         The function receives the string to parse (<code class="literal">inbuf</code>), the
 607         format mask to use (<code class="literal">fmtstr</code>) and a pointer to the timestamp
 608         variable that should hold the result of the operation
 609         (<code class="literal">dtvalue</code>).
 610        </p><p>
 611         This function is implemented by means of the <a class="xref" href="ecpg-pgtypes.html#PGTYPESTIMESTAMPDEFMTASC"><code class="function">PGTYPEStimestamp_defmt_asc</code></a> function. See the documentation
 612         there for a list of format specifiers that can be used.
 613        </p><p>
 614         The function returns 0 on success and a negative value in case of
 615         error.
 616        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-DTSUB"><span class="term"><code class="function">dtsub</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-DTSUB" class="id_link">#</a></dt><dd><p>
 617         Subtract one timestamp from another and return a variable of type
 618         interval.
 619 </p><pre class="synopsis">
 620 int dtsub(timestamp *ts1, timestamp *ts2, interval *iv);
 621 </pre><p>
 622         The function will subtract the timestamp variable that <code class="literal">ts2</code>
 623         points to from the timestamp variable that <code class="literal">ts1</code> points to
 624         and will store the result in the interval variable that <code class="literal">iv</code>
 625         points to.
 626        </p><p>
 627         Upon success, the function returns 0 and a negative value if an
 628         error occurred.
 629        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-DTTOASC"><span class="term"><code class="function">dttoasc</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-DTTOASC" class="id_link">#</a></dt><dd><p>
 630         Convert a timestamp variable to a C char* string.
 631 </p><pre class="synopsis">
 632 int dttoasc(timestamp *ts, char *output);
 633 </pre><p>
 634         The function receives a pointer to the timestamp variable to convert
 635         (<code class="literal">ts</code>) and the string that should hold the result of the
 636         operation (<code class="literal">output</code>). It converts <code class="literal">ts</code> to its
 637         textual representation according to the SQL standard, which is
 638         be <code class="literal">YYYY-MM-DD HH:MM:SS</code>.
 639        </p><p>
 640         Upon success, the function returns 0 and a negative value if an
 641         error occurred.
 642        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-DTTOFMTASC"><span class="term"><code class="function">dttofmtasc</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-DTTOFMTASC" class="id_link">#</a></dt><dd><p>
 643         Convert a timestamp variable to a C char* using a format mask.
 644 </p><pre class="synopsis">
 645 int dttofmtasc(timestamp *ts, char *output, int str_len, char *fmtstr);
 646 </pre><p>
 647         The function receives a pointer to the timestamp to convert as its
 648         first argument (<code class="literal">ts</code>), a pointer to the output buffer
 649         (<code class="literal">output</code>), the maximal length that has been allocated for
 650         the output buffer (<code class="literal">str_len</code>) and the format mask to
 651         use for the conversion (<code class="literal">fmtstr</code>).
 652        </p><p>
 653         Upon success, the function returns 0 and a negative value if an
 654         error occurred.
 655        </p><p>
 656         Internally, this function uses the <a class="xref" href="ecpg-pgtypes.html#PGTYPESTIMESTAMPFMTASC"><code class="function">PGTYPEStimestamp_fmt_asc</code></a> function. See the reference there for
 657         information on what format mask specifiers can be used.
 658        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-INTOASC"><span class="term"><code class="function">intoasc</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-INTOASC" class="id_link">#</a></dt><dd><p>
 659         Convert an interval variable to a C char* string.
 660 </p><pre class="synopsis">
 661 int intoasc(interval *i, char *str);
 662 </pre><p>
 663         The function receives a pointer to the interval variable to convert
 664         (<code class="literal">i</code>) and the string that should hold the result of the
 665         operation (<code class="literal">str</code>). It converts <code class="literal">i</code> to its
 666         textual representation according to the SQL standard, which is
 667         be <code class="literal">YYYY-MM-DD HH:MM:SS</code>.
 668        </p><p>
 669         Upon success, the function returns 0 and a negative value if an
 670         error occurred.
 671        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-RFMTLONG"><span class="term"><code class="function">rfmtlong</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-RFMTLONG" class="id_link">#</a></dt><dd><p>
 672         Convert a long integer value to its textual representation using a
 673         format mask.
 674 </p><pre class="synopsis">
 675 int rfmtlong(long lng_val, char *fmt, char *outbuf);
 676 </pre><p>
 677         The function receives the long value <code class="literal">lng_val</code>, the format
 678         mask <code class="literal">fmt</code> and a pointer to the output buffer
 679         <code class="literal">outbuf</code>. It converts the long value according to the format
 680         mask to its textual representation.
 681        </p><p>
 682         The format mask can be composed of the following format specifying
 683         characters:
 684         </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
 685            <code class="literal">*</code> (asterisk) - if this position would be blank
 686            otherwise, fill it with an asterisk.
 687           </p></li><li class="listitem"><p>
 688            <code class="literal">&amp;</code> (ampersand) - if this position would be
 689            blank otherwise, fill it with a zero.
 690           </p></li><li class="listitem"><p>
 691            <code class="literal">#</code> - turn leading zeroes into blanks.
 692           </p></li><li class="listitem"><p>
 693            <code class="literal">&lt;</code> - left-justify the number in the string.
 694           </p></li><li class="listitem"><p>
 695            <code class="literal">,</code> (comma) - group numbers of four or more digits
 696            into groups of three digits separated by a comma.
 697           </p></li><li class="listitem"><p>
 698            <code class="literal">.</code> (period) - this character separates the
 699            whole-number part of the number from the fractional part.
 700           </p></li><li class="listitem"><p>
 701            <code class="literal">-</code> (minus) - the minus sign appears if the number
 702            is a negative value.
 703           </p></li><li class="listitem"><p>
 704            <code class="literal">+</code> (plus) - the plus sign appears if the number is
 705            a positive value.
 706           </p></li><li class="listitem"><p>
 707            <code class="literal">(</code> - this replaces the minus sign in front of the
 708            negative number. The minus sign will not appear.
 709           </p></li><li class="listitem"><p>
 710            <code class="literal">)</code> - this character replaces the minus and is
 711            printed behind the negative value.
 712           </p></li><li class="listitem"><p>
 713            <code class="literal">$</code> - the currency symbol.
 714           </p></li></ul></div><p>
 715        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-RUPSHIFT"><span class="term"><code class="function">rupshift</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-RUPSHIFT" class="id_link">#</a></dt><dd><p>
 716         Convert a string to upper case.
 717 </p><pre class="synopsis">
 718 void rupshift(char *str);
 719 </pre><p>
 720         The function receives a pointer to the string and transforms every
 721         lower case character to upper case.
 722        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-BYLENG"><span class="term"><code class="function">byleng</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-BYLENG" class="id_link">#</a></dt><dd><p>
 723         Return the number of characters in a string without counting trailing
 724         blanks.
 725 </p><pre class="synopsis">
 726 int byleng(char *str, int len);
 727 </pre><p>
 728         The function expects a fixed-length string as its first argument
 729         (<code class="literal">str</code>) and its length as its second argument
 730         (<code class="literal">len</code>). It returns the number of significant characters,
 731         that is the length of the string without trailing blanks.
 732        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-LDCHAR"><span class="term"><code class="function">ldchar</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-LDCHAR" class="id_link">#</a></dt><dd><p>
 733         Copy a fixed-length string into a null-terminated string.
 734 </p><pre class="synopsis">
 735 void ldchar(char *src, int len, char *dest);
 736 </pre><p>
 737         The function receives the fixed-length string to copy
 738         (<code class="literal">src</code>), its length (<code class="literal">len</code>) and a pointer to the
 739         destination memory (<code class="literal">dest</code>). Note that you need to reserve at
 740         least <code class="literal">len+1</code> bytes for the string that <code class="literal">dest</code>
 741         points to. The function copies at most <code class="literal">len</code> bytes to the new
 742         location (less if the source string has trailing blanks) and adds the
 743         null-terminator.
 744        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-RGETMSG"><span class="term"><code class="function">rgetmsg</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-RGETMSG" class="id_link">#</a></dt><dd><p>
 745 </p><pre class="synopsis">
 746 int rgetmsg(int msgnum, char *s, int maxsize);
 747 </pre><p>
 748         This function exists but is not implemented at the moment!
 749        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-RTYPALIGN"><span class="term"><code class="function">rtypalign</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-RTYPALIGN" class="id_link">#</a></dt><dd><p>
 750 </p><pre class="synopsis">
 751 int rtypalign(int offset, int type);
 752 </pre><p>
 753         This function exists but is not implemented at the moment!
 754        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-RTYPMSIZE"><span class="term"><code class="function">rtypmsize</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-RTYPMSIZE" class="id_link">#</a></dt><dd><p>
 755 </p><pre class="synopsis">
 756 int rtypmsize(int type, int len);
 757 </pre><p>
 758         This function exists but is not implemented at the moment!
 759        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-RTYPWIDTH"><span class="term"><code class="function">rtypwidth</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-RTYPWIDTH" class="id_link">#</a></dt><dd><p>
 760 </p><pre class="synopsis">
 761 int rtypwidth(int sqltype, int sqllen);
 762 </pre><p>
 763         This function exists but is not implemented at the moment!
 764        </p></dd><dt id="RSETNULL"><span class="term"><code class="function">rsetnull</code></span> <a href="#RSETNULL" class="id_link">#</a></dt><dd><p>
 765         Set a variable to NULL.
 766 </p><pre class="synopsis">
 767 int rsetnull(int t, char *ptr);
 768 </pre><p>
 769         The function receives an integer that indicates the type of the
 770         variable and a pointer to the variable itself that is cast to a C
 771         char* pointer.
 772        </p><p>
 773         The following types exist:
 774         </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
 775            <code class="literal">CCHARTYPE</code> - For a variable of type <code class="type">char</code> or <code class="type">char*</code>
 776           </p></li><li class="listitem"><p>
 777            <code class="literal">CSHORTTYPE</code> - For a variable of type <code class="type">short int</code>
 778           </p></li><li class="listitem"><p>
 779            <code class="literal">CINTTYPE</code> - For a variable of type <code class="type">int</code>
 780           </p></li><li class="listitem"><p>
 781            <code class="literal">CBOOLTYPE</code> - For a variable of type <code class="type">boolean</code>
 782           </p></li><li class="listitem"><p>
 783            <code class="literal">CFLOATTYPE</code> - For a variable of type <code class="type">float</code>
 784           </p></li><li class="listitem"><p>
 785            <code class="literal">CLONGTYPE</code> - For a variable of type <code class="type">long</code>
 786           </p></li><li class="listitem"><p>
 787            <code class="literal">CDOUBLETYPE</code> - For a variable of type <code class="type">double</code>
 788           </p></li><li class="listitem"><p>
 789            <code class="literal">CDECIMALTYPE</code> - For a variable of type <code class="type">decimal</code>
 790           </p></li><li class="listitem"><p>
 791            <code class="literal">CDATETYPE</code> - For a variable of type <code class="type">date</code>
 792           </p></li><li class="listitem"><p>
 793            <code class="literal">CDTIMETYPE</code> - For a variable of type <code class="type">timestamp</code>
 794           </p></li></ul></div><p>
 795        </p><p>
 796         Here is an example of a call to this function:
 797 </p><pre class="programlisting">
 798 $char c[] = "abc       ";
 799 $short s = 17;
 800 $int i = -74874;
 801
 802 rsetnull(CCHARTYPE, (char *) c);
 803 rsetnull(CSHORTTYPE, (char *) &amp;s);
 804 rsetnull(CINTTYPE, (char *) &amp;i);
 805
 806 </pre><p>
 807        </p></dd><dt id="ECPG-INFORMIX-FUNCTIONS-RISNULL"><span class="term"><code class="function">risnull</code></span> <a href="#ECPG-INFORMIX-FUNCTIONS-RISNULL" class="id_link">#</a></dt><dd><p>
 808         Test if a variable is NULL.
 809 </p><pre class="synopsis">
 810 int risnull(int t, char *ptr);
 811 </pre><p>
 812         The function receives the type of the variable to test (<code class="literal">t</code>)
 813         as well a pointer to this variable (<code class="literal">ptr</code>). Note that the
 814         latter needs to be cast to a char*. See the function <a class="xref" href="ecpg-informix-compat.html#RSETNULL"><code class="function">rsetnull</code></a> for a list of possible variable types.
 815        </p><p>
 816         Here is an example of how to use this function:
 817 </p><pre class="programlisting">
 818 $char c[] = "abc       ";
 819 $short s = 17;
 820 $int i = -74874;
 821
 822 risnull(CCHARTYPE, (char *) c);
 823 risnull(CSHORTTYPE, (char *) &amp;s);
 824 risnull(CINTTYPE, (char *) &amp;i);
 825
 826 </pre><p>
 827        </p></dd></dl></div><p>
 828    </p></div><div class="sect2" id="ECPG-INFORMIX-CONSTANTS"><div class="titlepage"><div><div><h3 class="title">34.15.5. Additional Constants <a href="#ECPG-INFORMIX-CONSTANTS" class="id_link">#</a></h3></div></div></div><p>
 829     Note that all constants here describe errors and all of them are defined
 830     to represent negative values. In the descriptions of the different
 831     constants you can also find the value that the constants represent in the
 832     current implementation. However you should not rely on this number. You can
 833     however rely on the fact all of them are defined to represent negative
 834     values.
 835     </p><div class="variablelist"><dl class="variablelist"><dt id="ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-NUM-OVERFLOW"><span class="term"><code class="literal">ECPG_INFORMIX_NUM_OVERFLOW</code></span> <a href="#ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-NUM-OVERFLOW" class="id_link">#</a></dt><dd><p>
 836         Functions return this value if an overflow occurred in a
 837         calculation. Internally it is defined as -1200 (the <span class="productname">Informix</span>
 838         definition).
 839        </p></dd><dt id="ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-NUM-UNDERFLOW"><span class="term"><code class="literal">ECPG_INFORMIX_NUM_UNDERFLOW</code></span> <a href="#ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-NUM-UNDERFLOW" class="id_link">#</a></dt><dd><p>
 840         Functions return this value if an underflow occurred in a calculation.
 841         Internally it is defined as -1201 (the <span class="productname">Informix</span> definition).
 842        </p></dd><dt id="ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-DIVIDE-ZERO"><span class="term"><code class="literal">ECPG_INFORMIX_DIVIDE_ZERO</code></span> <a href="#ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-DIVIDE-ZERO" class="id_link">#</a></dt><dd><p>
 843         Functions return this value if an attempt to divide by zero is
 844         observed. Internally it is defined as -1202 (the <span class="productname">Informix</span> definition).
 845        </p></dd><dt id="ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-BAD-YEAR"><span class="term"><code class="literal">ECPG_INFORMIX_BAD_YEAR</code></span> <a href="#ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-BAD-YEAR" class="id_link">#</a></dt><dd><p>
 846         Functions return this value if a bad value for a year was found while
 847         parsing a date. Internally it is defined as -1204 (the <span class="productname">Informix</span>
 848         definition).
 849        </p></dd><dt id="ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-BAD-MONTH"><span class="term"><code class="literal">ECPG_INFORMIX_BAD_MONTH</code></span> <a href="#ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-BAD-MONTH" class="id_link">#</a></dt><dd><p>
 850         Functions return this value if a bad value for a month was found while
 851         parsing a date. Internally it is defined as -1205 (the <span class="productname">Informix</span>
 852         definition).
 853        </p></dd><dt id="ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-BAD-DAY"><span class="term"><code class="literal">ECPG_INFORMIX_BAD_DAY</code></span> <a href="#ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-BAD-DAY" class="id_link">#</a></dt><dd><p>
 854         Functions return this value if a bad value for a day was found while
 855         parsing a date. Internally it is defined as -1206 (the <span class="productname">Informix</span>
 856         definition).
 857        </p></dd><dt id="ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-ENOSHORTDATE"><span class="term"><code class="literal">ECPG_INFORMIX_ENOSHORTDATE</code></span> <a href="#ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-ENOSHORTDATE" class="id_link">#</a></dt><dd><p>
 858         Functions return this value if a parsing routine needs a short date
 859         representation but did not get the date string in the right length.
 860         Internally it is defined as -1209 (the <span class="productname">Informix</span> definition).
 861        </p></dd><dt id="ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-DATE-CONVERT"><span class="term"><code class="literal">ECPG_INFORMIX_DATE_CONVERT</code></span> <a href="#ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-DATE-CONVERT" class="id_link">#</a></dt><dd><p>
 862         Functions return this value if an error occurred during date
 863         formatting.  Internally it is defined as -1210 (the
 864         <span class="productname">Informix</span> definition).
 865        </p></dd><dt id="ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-OUT-OF-MEMORY"><span class="term"><code class="literal">ECPG_INFORMIX_OUT_OF_MEMORY</code></span> <a href="#ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-OUT-OF-MEMORY" class="id_link">#</a></dt><dd><p>
 866         Functions return this value if memory was exhausted during
 867         their operation.  Internally it is defined as -1211 (the
 868         <span class="productname">Informix</span> definition).
 869        </p></dd><dt id="ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-ENOTDMY"><span class="term"><code class="literal">ECPG_INFORMIX_ENOTDMY</code></span> <a href="#ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-ENOTDMY" class="id_link">#</a></dt><dd><p>
 870         Functions return this value if a parsing routine was supposed to get a
 871         format mask (like <code class="literal">mmddyy</code>) but not all fields were listed
 872         correctly. Internally it is defined as -1212 (the <span class="productname">Informix</span> definition).
 873        </p></dd><dt id="ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-BAD-NUMERIC"><span class="term"><code class="literal">ECPG_INFORMIX_BAD_NUMERIC</code></span> <a href="#ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-BAD-NUMERIC" class="id_link">#</a></dt><dd><p>
 874         Functions return this value either if a parsing routine cannot parse
 875         the textual representation for a numeric value because it contains
 876         errors or if a routine cannot complete a calculation involving numeric
 877         variables because at least one of the numeric variables is invalid.
 878         Internally it is defined as -1213 (the <span class="productname">Informix</span> definition).
 879        </p></dd><dt id="ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-BAD-EXPONENT"><span class="term"><code class="literal">ECPG_INFORMIX_BAD_EXPONENT</code></span> <a href="#ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-BAD-EXPONENT" class="id_link">#</a></dt><dd><p>
 880         Functions return this value if a parsing routine cannot parse
 881         an exponent.  Internally it is defined as -1216 (the
 882         <span class="productname">Informix</span> definition).
 883        </p></dd><dt id="ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-BAD-DATE"><span class="term"><code class="literal">ECPG_INFORMIX_BAD_DATE</code></span> <a href="#ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-BAD-DATE" class="id_link">#</a></dt><dd><p>
 884         Functions return this value if a parsing routine cannot parse
 885         a date.  Internally it is defined as -1218 (the
 886         <span class="productname">Informix</span> definition).
 887        </p></dd><dt id="ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-EXTRA-CHARS"><span class="term"><code class="literal">ECPG_INFORMIX_EXTRA_CHARS</code></span> <a href="#ECPG-INFORMIX-CONSTANTS-ECPG-INFORMIX-EXTRA-CHARS" class="id_link">#</a></dt><dd><p>
 888         Functions return this value if a parsing routine is passed extra
 889         characters it cannot parse.  Internally it is defined as -1264 (the
 890         <span class="productname">Informix</span> definition).
 891        </p></dd></dl></div><p>
 892    </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-sql-whenever.html" title="WHENEVER">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-oracle-compat.html" title="34.16. Oracle Compatibility Mode">Next</a></td></tr><tr><td width="40%" align="left" valign="top">WHENEVER </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.16. <span class="productname">Oracle</span> Compatibility Mode</td></tr></table></div></body></html>