begriffs open source - ai-pg/blob - full-docs/src/sgml/html/ecpg-develop.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.17. Internals</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-oracle-compat.html" title="34.16. Oracle Compatibility Mode" /><link rel="next" href="information-schema.html" title="Chapter 35. The Information Schema" /></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.17. Internals</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-oracle-compat.html" title="34.16. Oracle Compatibility Mode">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="information-schema.html" title="Chapter 35. The Information Schema">Next</a></td></tr></table><hr /></div><div class="sect1" id="ECPG-DEVELOP"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.17. Internals <a href="#ECPG-DEVELOP" class="id_link">#</a></h2></div></div></div><p>
   3    This section explains how <span class="application">ECPG</span> works
   4    internally. This information can occasionally be useful to help
   5    users understand how to use <span class="application">ECPG</span>.
   6   </p><p>
   7     The first four lines written by <code class="command">ecpg</code> to the
   8     output are fixed lines.  Two are comments and two are include
   9     lines necessary to interface to the library.  Then the
  10     preprocessor reads through the file and writes output.  Normally
  11     it just echoes everything to the output.
  12    </p><p>
  13     When it sees an <code class="command">EXEC SQL</code> statement, it
  14     intervenes and changes it. The command starts with <code class="command">EXEC
  15     SQL</code> and ends with <code class="command">;</code>. Everything in
  16     between is treated as an <acronym class="acronym">SQL</acronym> statement and
  17     parsed for variable substitution.
  18    </p><p>
  19     Variable substitution occurs when a symbol starts with a colon
  20     (<code class="literal">:</code>). The variable with that name is looked up
  21     among the variables that were previously declared within a
  22     <code class="literal">EXEC SQL DECLARE</code> section.
  23    </p><p>
  24     The most important function in the library is
  25     <code class="function">ECPGdo</code>, which takes care of executing most
  26     commands. It takes a variable number of arguments. This can easily
  27     add up to 50 or so arguments, and we hope this will not be a
  28     problem on any platform.
  29    </p><p>
  30     The arguments are:
  31
  32     </p><div class="variablelist"><dl class="variablelist"><dt id="ECPG-DEVELOP-LINE-NUMBER"><span class="term">A line number</span> <a href="#ECPG-DEVELOP-LINE-NUMBER" class="id_link">#</a></dt><dd><p>
  33         This is the line number of the original line; used in error
  34         messages only.
  35        </p></dd><dt id="ECPG-DEVELOP-STRING"><span class="term">A string</span> <a href="#ECPG-DEVELOP-STRING" class="id_link">#</a></dt><dd><p>
  36         This is the <acronym class="acronym">SQL</acronym> command that is to be issued.
  37         It is modified by the input variables, i.e., the variables that
  38         where not known at compile time but are to be entered in the
  39         command. Where the variables should go the string contains
  40         <code class="literal">?</code>.
  41        </p></dd><dt id="ECPG-DEVELOP-INPUT-VARIABLES"><span class="term">Input variables</span> <a href="#ECPG-DEVELOP-INPUT-VARIABLES" class="id_link">#</a></dt><dd><p>
  42         Every input variable causes ten arguments to be created.  (See below.)
  43        </p></dd><dt id="ECPG-DEVELOP-ECPGT-EOIT"><span class="term"><em class="parameter"><code>ECPGt_EOIT</code></em></span> <a href="#ECPG-DEVELOP-ECPGT-EOIT" class="id_link">#</a></dt><dd><p>
  44         An <code class="type">enum</code> telling that there are no more input
  45         variables.
  46        </p></dd><dt id="ECPG-DEVELOP-OUTPUT-VARIABLES"><span class="term">Output variables</span> <a href="#ECPG-DEVELOP-OUTPUT-VARIABLES" class="id_link">#</a></dt><dd><p>
  47         Every output variable causes ten arguments to be created.
  48         (See below.)  These variables are filled by the function.
  49        </p></dd><dt id="ECPG-DEVELOP-ECPGT-EORT"><span class="term"><em class="parameter"><code>ECPGt_EORT</code></em></span> <a href="#ECPG-DEVELOP-ECPGT-EORT" class="id_link">#</a></dt><dd><p>
  50         An <code class="type">enum</code> telling that there are no more variables.
  51        </p></dd></dl></div><p>
  52    </p><p>
  53     For every variable that is part of the <acronym class="acronym">SQL</acronym>
  54     command, the function gets ten arguments:
  55
  56     </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
  57        The type as a special symbol.
  58       </p></li><li class="listitem"><p>
  59        A pointer to the value or a pointer to the pointer.
  60       </p></li><li class="listitem"><p>
  61        The size of the variable if it is a <code class="type">char</code> or <code class="type">varchar</code>.
  62       </p></li><li class="listitem"><p>
  63        The number of elements in the array (for array fetches).
  64       </p></li><li class="listitem"><p>
  65        The offset to the next element in the array (for array fetches).
  66       </p></li><li class="listitem"><p>
  67        The type of the indicator variable as a special symbol.
  68       </p></li><li class="listitem"><p>
  69        A pointer to the indicator variable.
  70       </p></li><li class="listitem"><p>
  71        0
  72       </p></li><li class="listitem"><p>
  73        The number of elements in the indicator array (for array fetches).
  74       </p></li><li class="listitem"><p>
  75        The offset to the next element in the indicator array (for
  76        array fetches).
  77       </p></li></ol></div><p>
  78    </p><p>
  79     Note that not all SQL commands are treated in this way.  For
  80     instance, an open cursor statement like:
  81 </p><pre class="programlisting">
  82 EXEC SQL OPEN <em class="replaceable"><code>cursor</code></em>;
  83 </pre><p>
  84     is not copied to the output. Instead, the cursor's
  85     <code class="command">DECLARE</code> command is used at the position of the <code class="command">OPEN</code> command
  86     because it indeed opens the cursor.
  87    </p><p>
  88     Here is a complete example describing the output of the
  89     preprocessor of a file <code class="filename">foo.pgc</code> (details might
  90     change with each particular version of the preprocessor):
  91 </p><pre class="programlisting">
  92 EXEC SQL BEGIN DECLARE SECTION;
  93 int index;
  94 int result;
  95 EXEC SQL END DECLARE SECTION;
  96 ...
  97 EXEC SQL SELECT res INTO :result FROM mytable WHERE index = :index;
  98 </pre><p>
  99     is translated into:
 100 </p><pre class="programlisting">
 101 /* Processed by ecpg (2.6.0) */
 102 /* These two include files are added by the preprocessor */
 103 #include &lt;ecpgtype.h&gt;;
 104 #include &lt;ecpglib.h&gt;;
 105
 106 /* exec sql begin declare section */
 107
 108 #line 1 "foo.pgc"
 109
 110  int index;
 111  int result;
 112 /* exec sql end declare section */
 113 ...
 114 ECPGdo(__LINE__, NULL, "SELECT res FROM mytable WHERE index = ?     ",
 115         ECPGt_int,&amp;(index),1L,1L,sizeof(int),
 116         ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EOIT,
 117         ECPGt_int,&amp;(result),1L,1L,sizeof(int),
 118         ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EORT);
 119 #line 147 "foo.pgc"
 120
 121 </pre><p>
 122     (The indentation here is added for readability and not
 123     something the preprocessor does.)
 124    </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-oracle-compat.html" title="34.16. Oracle Compatibility Mode">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="information-schema.html" title="Chapter 35. The Information Schema">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.16. <span class="productname">Oracle</span> Compatibility Mode </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"> Chapter 35. The Information Schema</td></tr></table></div></body></html>