begriffs open source - ai-pg/blob - full-docs/src/sgml/html/ecpg-cpp.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.13. C++ Applications</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-lo.html" title="34.12. Large Objects" /><link rel="next" href="ecpg-sql-commands.html" title="34.14. Embedded SQL Commands" /></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.13. <acronym class="acronym">C++</acronym> Applications</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-lo.html" title="34.12. Large Objects">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-sql-commands.html" title="34.14. Embedded SQL Commands">Next</a></td></tr></table><hr /></div><div class="sect1" id="ECPG-CPP"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.13. <acronym class="acronym">C++</acronym> Applications <a href="#ECPG-CPP" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ecpg-cpp.html#ECPG-CPP-SCOPE">34.13.1. Scope for Host Variables</a></span></dt><dt><span class="sect2"><a href="ecpg-cpp.html#ECPG-CPP-AND-C">34.13.2. C++ Application Development with External C Module</a></span></dt></dl></div><p>
   3    ECPG has some limited support for C++ applications.  This section
   4    describes some caveats.
   5   </p><p>
   6    The <code class="command">ecpg</code> preprocessor takes an input file
   7    written in C (or something like C) and embedded SQL commands,
   8    converts the embedded SQL commands into C language chunks, and
   9    finally generates a <code class="filename">.c</code> file.  The header file
  10    declarations of the library functions used by the C language chunks
  11    that <code class="command">ecpg</code> generates are wrapped
  12    in <code class="literal">extern "C" { ... }</code> blocks when used under
  13    C++, so they should work seamlessly in C++.
  14   </p><p>
  15    In general, however, the <code class="command">ecpg</code> preprocessor only
  16    understands C; it does not handle the special syntax and reserved
  17    words of the C++ language.  So, some embedded SQL code written in
  18    C++ application code that uses complicated features specific to C++
  19    might fail to be preprocessed correctly or might not work as
  20    expected.
  21   </p><p>
  22    A safe way to use the embedded SQL code in a C++ application is
  23    hiding the ECPG calls in a C module, which the C++ application code
  24    calls into to access the database, and linking that together with
  25    the rest of the C++ code.  See <a class="xref" href="ecpg-cpp.html#ECPG-CPP-AND-C" title="34.13.2. C++ Application Development with External C Module">Section 34.13.2</a>
  26    about that.
  27   </p><div class="sect2" id="ECPG-CPP-SCOPE"><div class="titlepage"><div><div><h3 class="title">34.13.1. Scope for Host Variables <a href="#ECPG-CPP-SCOPE" class="id_link">#</a></h3></div></div></div><p>
  28     The <code class="command">ecpg</code> preprocessor understands the scope of
  29     variables in C.  In the C language, this is rather simple because
  30     the scopes of variables is based on their code blocks.  In C++,
  31     however, the class member variables are referenced in a different
  32     code block from the declared position, so
  33     the <code class="command">ecpg</code> preprocessor will not understand the
  34     scope of the class member variables.
  35    </p><p>
  36     For example, in the following case, the <code class="command">ecpg</code>
  37     preprocessor cannot find any declaration for the
  38     variable <code class="literal">dbname</code> in the <code class="literal">test</code>
  39     method, so an error will occur.
  40
  41 </p><pre class="programlisting">
  42 class TestCpp
  43 {
  44     EXEC SQL BEGIN DECLARE SECTION;
  45     char dbname[1024];
  46     EXEC SQL END DECLARE SECTION;
  47
  48   public:
  49     TestCpp();
  50     void test();
  51     ~TestCpp();
  52 };
  53
  54 TestCpp::TestCpp()
  55 {
  56     EXEC SQL CONNECT TO testdb1;
  57     EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
  58 }
  59
  60 void Test::test()
  61 {
  62     EXEC SQL SELECT current_database() INTO :dbname;
  63     printf("current_database = %s\n", dbname);
  64 }
  65
  66 TestCpp::~TestCpp()
  67 {
  68     EXEC SQL DISCONNECT ALL;
  69 }
  70 </pre><p>
  71
  72     This code will result in an error like this:
  73 </p><pre class="screen">
  74 <strong class="userinput"><code>ecpg test_cpp.pgc</code></strong>
  75 test_cpp.pgc:28: ERROR: variable "dbname" is not declared
  76 </pre><p>
  77    </p><p>
  78     To avoid this scope issue, the <code class="literal">test</code> method
  79     could be modified to use a local variable as intermediate storage.
  80     But this approach is only a poor workaround, because it uglifies
  81     the code and reduces performance.
  82
  83 </p><pre class="programlisting">
  84 void TestCpp::test()
  85 {
  86     EXEC SQL BEGIN DECLARE SECTION;
  87     char tmp[1024];
  88     EXEC SQL END DECLARE SECTION;
  89
  90     EXEC SQL SELECT current_database() INTO :tmp;
  91     strlcpy(dbname, tmp, sizeof(tmp));
  92
  93     printf("current_database = %s\n", dbname);
  94 }
  95 </pre><p>
  96    </p></div><div class="sect2" id="ECPG-CPP-AND-C"><div class="titlepage"><div><div><h3 class="title">34.13.2. C++ Application Development with External C Module <a href="#ECPG-CPP-AND-C" class="id_link">#</a></h3></div></div></div><p>
  97     If you understand these technical limitations of
  98     the <code class="command">ecpg</code> preprocessor in C++, you might come to
  99     the conclusion that linking C objects and C++ objects at the link
 100     stage to enable C++ applications to use ECPG features could be
 101     better than writing some embedded SQL commands in C++ code
 102     directly.  This section describes a way to separate some embedded
 103     SQL commands from C++ application code with a simple example.  In
 104     this example, the application is implemented in C++, while C and
 105     ECPG is used to connect to the PostgreSQL server.
 106    </p><p>
 107     Three kinds of files have to be created: a C file
 108     (<code class="filename">*.pgc</code>), a header file, and a C++ file:
 109
 110     </p><div class="variablelist"><dl class="variablelist"><dt id="ECPG-CPP-AND-C-TEST-MOD-PGC"><span class="term"><code class="filename">test_mod.pgc</code></span> <a href="#ECPG-CPP-AND-C-TEST-MOD-PGC" class="id_link">#</a></dt><dd><p>
 111         A sub-routine module to execute SQL commands embedded in C.
 112         It is going to be converted
 113         into <code class="filename">test_mod.c</code> by the preprocessor.
 114
 115 </p><pre class="programlisting">
 116 #include "test_mod.h"
 117 #include &lt;stdio.h&gt;
 118
 119 void
 120 db_connect()
 121 {
 122     EXEC SQL CONNECT TO testdb1;
 123     EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
 124 }
 125
 126 void
 127 db_test()
 128 {
 129     EXEC SQL BEGIN DECLARE SECTION;
 130     char dbname[1024];
 131     EXEC SQL END DECLARE SECTION;
 132
 133     EXEC SQL SELECT current_database() INTO :dbname;
 134     printf("current_database = %s\n", dbname);
 135 }
 136
 137 void
 138 db_disconnect()
 139 {
 140     EXEC SQL DISCONNECT ALL;
 141 }
 142 </pre><p>
 143        </p></dd><dt id="ECPG-CPP-AND-C-TEST-MOD-H"><span class="term"><code class="filename">test_mod.h</code></span> <a href="#ECPG-CPP-AND-C-TEST-MOD-H" class="id_link">#</a></dt><dd><p>
 144         A header file with declarations of the functions in the C
 145         module (<code class="filename">test_mod.pgc</code>).  It is included by
 146         <code class="filename">test_cpp.cpp</code>.  This file has to have an
 147         <code class="literal">extern "C"</code> block around the declarations,
 148         because it will be linked from the C++ module.
 149
 150 </p><pre class="programlisting">
 151 #ifdef __cplusplus
 152 extern "C" {
 153 #endif
 154
 155 void db_connect();
 156 void db_test();
 157 void db_disconnect();
 158
 159 #ifdef __cplusplus
 160 }
 161 #endif
 162 </pre><p>
 163        </p></dd><dt id="ECPG-CPP-AND-C-TEST-CPP-CPP"><span class="term"><code class="filename">test_cpp.cpp</code></span> <a href="#ECPG-CPP-AND-C-TEST-CPP-CPP" class="id_link">#</a></dt><dd><p>
 164         The main code for the application, including
 165         the <code class="function">main</code> routine, and in this example a
 166         C++ class.
 167
 168 </p><pre class="programlisting">
 169 #include "test_mod.h"
 170
 171 class TestCpp
 172 {
 173   public:
 174     TestCpp();
 175     void test();
 176     ~TestCpp();
 177 };
 178
 179 TestCpp::TestCpp()
 180 {
 181     db_connect();
 182 }
 183
 184 void
 185 TestCpp::test()
 186 {
 187     db_test();
 188 }
 189
 190 TestCpp::~TestCpp()
 191 {
 192     db_disconnect();
 193 }
 194
 195 int
 196 main(void)
 197 {
 198     TestCpp *t = new TestCpp();
 199
 200     t-&gt;test();
 201     return 0;
 202 }
 203 </pre><p>
 204        </p></dd></dl></div><p>
 205    </p><p>
 206     To build the application, proceed as follows.  Convert
 207     <code class="filename">test_mod.pgc</code> into <code class="filename">test_mod.c</code> by
 208     running <code class="command">ecpg</code>, and generate
 209     <code class="filename">test_mod.o</code> by compiling
 210     <code class="filename">test_mod.c</code> with the C compiler:
 211 </p><pre class="programlisting">
 212 ecpg -o test_mod.c test_mod.pgc
 213 cc -c test_mod.c -o test_mod.o
 214 </pre><p>
 215    </p><p>
 216     Next, generate <code class="filename">test_cpp.o</code> by compiling
 217     <code class="filename">test_cpp.cpp</code> with the C++ compiler:
 218 </p><pre class="programlisting">
 219 c++ -c test_cpp.cpp -o test_cpp.o
 220 </pre><p>
 221    </p><p>
 222     Finally, link these object files, <code class="filename">test_cpp.o</code>
 223     and <code class="filename">test_mod.o</code>, into one executable, using the C++
 224     compiler driver:
 225 </p><pre class="programlisting">
 226 c++ test_cpp.o test_mod.o -lecpg -o test_cpp
 227 </pre><p>
 228    </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-lo.html" title="34.12. Large Objects">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-sql-commands.html" title="34.14. Embedded SQL Commands">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.12. Large Objects </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.14. Embedded SQL Commands</td></tr></table></div></body></html>