diff options
Diffstat (limited to 'doc/src/sgml/html/ecpg-develop.html')
| -rw-r--r-- | doc/src/sgml/html/ecpg-develop.html | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/doc/src/sgml/html/ecpg-develop.html b/doc/src/sgml/html/ecpg-develop.html new file mode 100644 index 0000000..3a45c88 --- /dev/null +++ b/doc/src/sgml/html/ecpg-develop.html @@ -0,0 +1,124 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!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.2 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> + This section explains how <span class="application">ECPG</span> works + internally. This information can occasionally be useful to help + users understand how to use <span class="application">ECPG</span>. + </p><p> + The first four lines written by <code class="command">ecpg</code> to the + output are fixed lines. Two are comments and two are include + lines necessary to interface to the library. Then the + preprocessor reads through the file and writes output. Normally + it just echoes everything to the output. + </p><p> + When it sees an <code class="command">EXEC SQL</code> statement, it + intervenes and changes it. The command starts with <code class="command">EXEC + SQL</code> and ends with <code class="command">;</code>. Everything in + between is treated as an <acronym class="acronym">SQL</acronym> statement and + parsed for variable substitution. + </p><p> + Variable substitution occurs when a symbol starts with a colon + (<code class="literal">:</code>). The variable with that name is looked up + among the variables that were previously declared within a + <code class="literal">EXEC SQL DECLARE</code> section. + </p><p> + The most important function in the library is + <code class="function">ECPGdo</code>, which takes care of executing most + commands. It takes a variable number of arguments. This can easily + add up to 50 or so arguments, and we hope this will not be a + problem on any platform. + </p><p> + The arguments are: + + </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> + This is the line number of the original line; used in error + messages only. + </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> + This is the <acronym class="acronym">SQL</acronym> command that is to be issued. + It is modified by the input variables, i.e., the variables that + where not known at compile time but are to be entered in the + command. Where the variables should go the string contains + <code class="literal">?</code>. + </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> + Every input variable causes ten arguments to be created. (See below.) + </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> + An <code class="type">enum</code> telling that there are no more input + variables. + </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> + Every output variable causes ten arguments to be created. + (See below.) These variables are filled by the function. + </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> + An <code class="type">enum</code> telling that there are no more variables. + </p></dd></dl></div><p> + </p><p> + For every variable that is part of the <acronym class="acronym">SQL</acronym> + command, the function gets ten arguments: + + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + The type as a special symbol. + </p></li><li class="listitem"><p> + A pointer to the value or a pointer to the pointer. + </p></li><li class="listitem"><p> + The size of the variable if it is a <code class="type">char</code> or <code class="type">varchar</code>. + </p></li><li class="listitem"><p> + The number of elements in the array (for array fetches). + </p></li><li class="listitem"><p> + The offset to the next element in the array (for array fetches). + </p></li><li class="listitem"><p> + The type of the indicator variable as a special symbol. + </p></li><li class="listitem"><p> + A pointer to the indicator variable. + </p></li><li class="listitem"><p> + 0 + </p></li><li class="listitem"><p> + The number of elements in the indicator array (for array fetches). + </p></li><li class="listitem"><p> + The offset to the next element in the indicator array (for + array fetches). + </p></li></ol></div><p> + </p><p> + Note that not all SQL commands are treated in this way. For + instance, an open cursor statement like: +</p><pre class="programlisting"> +EXEC SQL OPEN <em class="replaceable"><code>cursor</code></em>; +</pre><p> + is not copied to the output. Instead, the cursor's + <code class="command">DECLARE</code> command is used at the position of the <code class="command">OPEN</code> command + because it indeed opens the cursor. + </p><p> + Here is a complete example describing the output of the + preprocessor of a file <code class="filename">foo.pgc</code> (details might + change with each particular version of the preprocessor): +</p><pre class="programlisting"> +EXEC SQL BEGIN DECLARE SECTION; +int index; +int result; +EXEC SQL END DECLARE SECTION; +... +EXEC SQL SELECT res INTO :result FROM mytable WHERE index = :index; +</pre><p> + is translated into: +</p><pre class="programlisting"> +/* Processed by ecpg (2.6.0) */ +/* These two include files are added by the preprocessor */ +#include <ecpgtype.h>; +#include <ecpglib.h>; + +/* exec sql begin declare section */ + +#line 1 "foo.pgc" + + int index; + int result; +/* exec sql end declare section */ +... +ECPGdo(__LINE__, NULL, "SELECT res FROM mytable WHERE index = ? ", + ECPGt_int,&(index),1L,1L,sizeof(int), + ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EOIT, + ECPGt_int,&(result),1L,1L,sizeof(int), + ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EORT); +#line 147 "foo.pgc" + +</pre><p> + (The indentation here is added for readability and not + something the preprocessor does.) + </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.2 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 37. The Information Schema</td></tr></table></div></body></html>
\ No newline at end of file |