codekingpro/portable-devtools

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>36.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="36.16. Oracle Compatibility Mode" /><link rel="next" href="information-schema.html" title="Chapter 37. 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">36.17. Internals</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-oracle-compat.html" title="36.16. Oracle Compatibility Mode">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><th width="60%" align="center">Chapter 36. <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 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="information-schema.html" title="Chapter 37. 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">36.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> works4   internally. This information can occasionally be useful to help5   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 the8    output are fixed lines.  Two are comments and two are include9    lines necessary to interface to the library.  Then the10    preprocessor reads through the file and writes output.  Normally11    it just echoes everything to the output.12   </p><p>13    When it sees an <code class="command">EXEC SQL</code> statement, it14    intervenes and changes it. The command starts with <code class="command">EXEC15    SQL</code> and ends with <code class="command">;</code>. Everything in16    between is treated as an <acronym class="acronym">SQL</acronym> statement and17    parsed for variable substitution.18   </p><p>19    Variable substitution occurs when a symbol starts with a colon20    (<code class="literal">:</code>). The variable with that name is looked up21    among the variables that were previously declared within a22    <code class="literal">EXEC SQL DECLARE</code> section.23   </p><p>24    The most important function in the library is25    <code class="function">ECPGdo</code>, which takes care of executing most26    commands. It takes a variable number of arguments. This can easily27    add up to 50 or so arguments, and we hope this will not be a28    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 error34        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 that38        where not known at compile time but are to be entered in the39        command. Where the variables should go the string contains40        <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 input45        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       072      </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 (for76       array fetches).77      </p></li></ol></div><p>78   </p><p>79    Note that not all SQL commands are treated in this way.  For80    instance, an open cursor statement like:81</p><pre class="programlisting">82EXEC SQL OPEN <em class="replaceable"><code>cursor</code></em>;83</pre><p>84    is not copied to the output. Instead, the cursor's85    <code class="command">DECLARE</code> command is used at the position of the <code class="command">OPEN</code> command86    because it indeed opens the cursor.87   </p><p>88    Here is a complete example describing the output of the89    preprocessor of a file <code class="filename">foo.pgc</code> (details might90    change with each particular version of the preprocessor):91</p><pre class="programlisting">92EXEC SQL BEGIN DECLARE SECTION;93int index;94int result;95EXEC SQL END DECLARE SECTION;96...97EXEC 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...114ECPGdo(__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 not123    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="36.16. Oracle Compatibility Mode">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="information-schema.html" title="Chapter 37. The Information Schema">Next</a></td></tr><tr><td width="40%" align="left" valign="top">36.16. <span class="productname">Oracle</span> Compatibility Mode </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 37. The Information Schema</td></tr></table></div></body></html>