← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/postgresql-9.1/oneiric-security

« back to all changes in this revision

Viewing changes to doc/src/sgml/html/ecpg-cpp.html

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2011-05-11 10:41:53 UTC
  • Revision ID: james.westby@ubuntu.com-20110511104153-psbh2o58553fv1m0
Tags: upstream-9.1~beta1
Import upstream version 9.1~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/html/ecpg-cpp.html
 
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 
2
<HTML
 
3
><HEAD
 
4
><TITLE
 
5
>C++ Applications</TITLE
 
6
><META
 
7
NAME="GENERATOR"
 
8
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
 
9
REV="MADE"
 
10
HREF="mailto:pgsql-docs@postgresql.org"><LINK
 
11
REL="HOME"
 
12
TITLE="PostgreSQL 9.1beta1 Documentation"
 
13
HREF="index.html"><LINK
 
14
REL="UP"
 
15
TITLE="ECPG - Embedded SQL in C"
 
16
HREF="ecpg.html"><LINK
 
17
REL="PREVIOUS"
 
18
TITLE="Large Objects"
 
19
HREF="ecpg-lo.html"><LINK
 
20
REL="NEXT"
 
21
TITLE="Embedded SQL Commands"
 
22
HREF="ecpg-sql-commands.html"><LINK
 
23
REL="STYLESHEET"
 
24
TYPE="text/css"
 
25
HREF="stylesheet.css"><META
 
26
HTTP-EQUIV="Content-Type"
 
27
CONTENT="text/html; charset=ISO-8859-1"><META
 
28
NAME="creation"
 
29
CONTENT="2011-04-27T21:20:33"></HEAD
 
30
><BODY
 
31
CLASS="SECT1"
 
32
><DIV
 
33
CLASS="NAVHEADER"
 
34
><TABLE
 
35
SUMMARY="Header navigation table"
 
36
WIDTH="100%"
 
37
BORDER="0"
 
38
CELLPADDING="0"
 
39
CELLSPACING="0"
 
40
><TR
 
41
><TH
 
42
COLSPAN="5"
 
43
ALIGN="center"
 
44
VALIGN="bottom"
 
45
><A
 
46
HREF="index.html"
 
47
>PostgreSQL 9.1beta1 Documentation</A
 
48
></TH
 
49
></TR
 
50
><TR
 
51
><TD
 
52
WIDTH="10%"
 
53
ALIGN="left"
 
54
VALIGN="top"
 
55
><A
 
56
TITLE="Large Objects"
 
57
HREF="ecpg-lo.html"
 
58
ACCESSKEY="P"
 
59
>Prev</A
 
60
></TD
 
61
><TD
 
62
WIDTH="10%"
 
63
ALIGN="left"
 
64
VALIGN="top"
 
65
><A
 
66
TITLE="ECPG - Embedded SQL in C"
 
67
HREF="ecpg.html"
 
68
>Fast Backward</A
 
69
></TD
 
70
><TD
 
71
WIDTH="60%"
 
72
ALIGN="center"
 
73
VALIGN="bottom"
 
74
>Chapter 33. <SPAN
 
75
CLASS="APPLICATION"
 
76
>ECPG</SPAN
 
77
> - Embedded <ACRONYM
 
78
CLASS="ACRONYM"
 
79
>SQL</ACRONYM
 
80
> in C</TD
 
81
><TD
 
82
WIDTH="10%"
 
83
ALIGN="right"
 
84
VALIGN="top"
 
85
><A
 
86
TITLE="ECPG - Embedded SQL in C"
 
87
HREF="ecpg.html"
 
88
>Fast Forward</A
 
89
></TD
 
90
><TD
 
91
WIDTH="10%"
 
92
ALIGN="right"
 
93
VALIGN="top"
 
94
><A
 
95
TITLE="Embedded SQL Commands"
 
96
HREF="ecpg-sql-commands.html"
 
97
ACCESSKEY="N"
 
98
>Next</A
 
99
></TD
 
100
></TR
 
101
></TABLE
 
102
><HR
 
103
ALIGN="LEFT"
 
104
WIDTH="100%"></DIV
 
105
><DIV
 
106
CLASS="SECT1"
 
107
><H1
 
108
CLASS="SECT1"
 
109
><A
 
110
NAME="ECPG-CPP"
 
111
>33.13. <ACRONYM
 
112
CLASS="ACRONYM"
 
113
>C++</ACRONYM
 
114
> Applications</A
 
115
></H1
 
116
><P
 
117
>   ECPG has some limited support for C++ applications.  This section
 
118
   describes some caveats.
 
119
  </P
 
120
><P
 
121
>   The <TT
 
122
CLASS="COMMAND"
 
123
>ecpg</TT
 
124
> preprocessor takes an input file
 
125
   written in C (or something like C) and embedded SQL commands,
 
126
   converts the embedded SQL commands into C language chunks, and
 
127
   finally generates a <TT
 
128
CLASS="FILENAME"
 
129
>.c</TT
 
130
> file.  The header file
 
131
   declarations of the library functions used by the C language chunks
 
132
   that <TT
 
133
CLASS="COMMAND"
 
134
>ecpg</TT
 
135
> generates are wrapped
 
136
   in <TT
 
137
CLASS="LITERAL"
 
138
>extern "C" { ... }</TT
 
139
> blocks when used under
 
140
   C++, so they should work seamlessly in C++.
 
141
  </P
 
142
><P
 
143
>   In general, however, the <TT
 
144
CLASS="COMMAND"
 
145
>ecpg</TT
 
146
> preprocessor only
 
147
   understands C; it does not handle the special syntax and reserved
 
148
   words of the C++ language.  So, some embedded SQL code written in
 
149
   C++ application code that uses complicated features specific to C++
 
150
   might fail to be preprocessed correctly or might not work as
 
151
   expected.
 
152
  </P
 
153
><P
 
154
>   A safe way to use the embedded SQL code in a C++ application is
 
155
   hiding the ECPG calls in a C module, which the C++ application code
 
156
   calls into to access the database, and linking that together with
 
157
   the rest of the C++ code.  See <A
 
158
HREF="ecpg-cpp.html#ECPG-CPP-AND-C"
 
159
>Section 33.13.2</A
 
160
>
 
161
   about that.
 
162
  </P
 
163
><DIV
 
164
CLASS="SECT2"
 
165
><H2
 
166
CLASS="SECT2"
 
167
><A
 
168
NAME="ECPG-CPP-SCOPE"
 
169
>33.13.1. Scope for Host Variables</A
 
170
></H2
 
171
><P
 
172
>    The <TT
 
173
CLASS="COMMAND"
 
174
>ecpg</TT
 
175
> preprocessor understands the scope of
 
176
    variables in C.  In the C language, this is rather simple because
 
177
    the scopes of variables is based on their code blocks.  In C++,
 
178
    however, the class member variables are referenced in a different
 
179
    code block from the declared position, so
 
180
    the <TT
 
181
CLASS="COMMAND"
 
182
>ecpg</TT
 
183
> preprocessor will not understand the
 
184
    scope of the class member variables.
 
185
   </P
 
186
><P
 
187
>    For example, in the following case, the <TT
 
188
CLASS="COMMAND"
 
189
>ecpg</TT
 
190
>
 
191
    preprocessor cannot find any declaration for the
 
192
    variable <TT
 
193
CLASS="LITERAL"
 
194
>dbname</TT
 
195
> in the <TT
 
196
CLASS="LITERAL"
 
197
>test</TT
 
198
>
 
199
    method, so an error will occur.
 
200
 
 
201
</P><PRE
 
202
CLASS="PROGRAMLISTING"
 
203
>class TestCpp
 
204
{
 
205
    EXEC SQL BEGIN DECLARE SECTION;
 
206
    char dbname[1024];
 
207
    EXEC SQL END DECLARE SECTION;
 
208
 
 
209
  public:
 
210
    TestCpp();
 
211
    void test();
 
212
    ~TestCpp();
 
213
};
 
214
 
 
215
TestCpp::TestCpp()
 
216
{
 
217
    EXEC SQL CONNECT TO testdb1;
 
218
}
 
219
 
 
220
void Test::test()
 
221
{
 
222
    EXEC SQL SELECT current_database() INTO :dbname;
 
223
    printf("current_database = %s\n", dbname);
 
224
}
 
225
 
 
226
TestCpp::~TestCpp()
 
227
{
 
228
    EXEC SQL DISCONNECT ALL;
 
229
}</PRE
 
230
><P>
 
231
 
 
232
    This code will result in an error like this:
 
233
</P><PRE
 
234
CLASS="SCREEN"
 
235
><KBD
 
236
CLASS="USERINPUT"
 
237
>ecpg test_cpp.pgc</KBD
 
238
>
 
239
test_cpp.pgc:28: ERROR: variable "dbname" is not declared</PRE
 
240
><P>
 
241
   </P
 
242
><P
 
243
>    To avoid this scope issue, the <TT
 
244
CLASS="LITERAL"
 
245
>test</TT
 
246
> method
 
247
    could be modified to use a local variable as intermediate storage.
 
248
    But this approach is only a poor workaround, because it uglifies
 
249
    the code and reduces performance.
 
250
 
 
251
</P><PRE
 
252
CLASS="PROGRAMLISTING"
 
253
>void TestCpp::test()
 
254
{
 
255
    EXEC SQL BEGIN DECLARE SECTION;
 
256
    char tmp[1024];
 
257
    EXEC SQL END DECLARE SECTION;
 
258
 
 
259
    EXEC SQL SELECT current_database() INTO :tmp;
 
260
    strlcpy(dbname, tmp, sizeof(tmp));
 
261
 
 
262
    printf("current_database = %s\n", dbname);
 
263
}</PRE
 
264
><P>
 
265
   </P
 
266
></DIV
 
267
><DIV
 
268
CLASS="SECT2"
 
269
><H2
 
270
CLASS="SECT2"
 
271
><A
 
272
NAME="ECPG-CPP-AND-C"
 
273
>33.13.2. C++ Application Development with External C Module</A
 
274
></H2
 
275
><P
 
276
>    If you understand these technical limitations of
 
277
    the <TT
 
278
CLASS="COMMAND"
 
279
>ecpg</TT
 
280
> preprocessor in C++, you might come to
 
281
    the conclusion that linking C objects and C++ objects at the link
 
282
    stage to enable C++ applications to use ECPG features could be
 
283
    better than writing some embedded SQL commands in C++ code
 
284
    directly.  This section describes a way to separate some embedded
 
285
    SQL commands from C++ application code with a simple example.  In
 
286
    this example, the application is implemented in C++, while C and
 
287
    ECPG is used to connect to the PostgreSQL server.
 
288
   </P
 
289
><P
 
290
>    Three kinds of files have to be created: a C file
 
291
    (<TT
 
292
CLASS="FILENAME"
 
293
>*.pgc</TT
 
294
>), a header file, and a C++ file:
 
295
 
 
296
    <P
 
297
></P
 
298
></P><DIV
 
299
CLASS="VARIABLELIST"
 
300
><DL
 
301
><DT
 
302
><TT
 
303
CLASS="FILENAME"
 
304
>test_mod.pgc</TT
 
305
></DT
 
306
><DD
 
307
><P
 
308
>        A sub-routine module to execute SQL commands embedded in C.
 
309
        It is going to be converted
 
310
        into <TT
 
311
CLASS="FILENAME"
 
312
>test_mod.c</TT
 
313
> by the preprocessor.
 
314
 
 
315
</P><PRE
 
316
CLASS="PROGRAMLISTING"
 
317
>#include "test_mod.h"
 
318
#include &lt;stdio.h&gt;
 
319
 
 
320
void
 
321
db_connect()
 
322
{
 
323
    EXEC SQL CONNECT TO testdb1;
 
324
}
 
325
 
 
326
void
 
327
db_test()
 
328
{
 
329
    EXEC SQL BEGIN DECLARE SECTION;
 
330
    char dbname[1024];
 
331
    EXEC SQL END DECLARE SECTION;
 
332
 
 
333
    EXEC SQL SELECT current_database() INTO :dbname;
 
334
    printf("current_database = %s\n", dbname);
 
335
}
 
336
 
 
337
void
 
338
db_disconnect()
 
339
{
 
340
    EXEC SQL DISCONNECT ALL;
 
341
}</PRE
 
342
><P>
 
343
       </P
 
344
></DD
 
345
><DT
 
346
><TT
 
347
CLASS="FILENAME"
 
348
>test_mod.h</TT
 
349
></DT
 
350
><DD
 
351
><P
 
352
>        A header file with declarations of the functions in the C
 
353
        module (<TT
 
354
CLASS="FILENAME"
 
355
>test_mod.pgc</TT
 
356
>).  It is included by
 
357
        <TT
 
358
CLASS="FILENAME"
 
359
>test_cpp.cpp</TT
 
360
>.  This file has to have an
 
361
        <TT
 
362
CLASS="LITERAL"
 
363
>extern "C"</TT
 
364
> block around the declarations,
 
365
        because it will be linked from the C++ module.
 
366
 
 
367
</P><PRE
 
368
CLASS="PROGRAMLISTING"
 
369
>#ifdef __cplusplus
 
370
extern "C" {
 
371
#endif
 
372
 
 
373
void db_connect();
 
374
void db_test();
 
375
void db_disconnect();
 
376
 
 
377
#ifdef __cplusplus
 
378
}
 
379
#endif</PRE
 
380
><P>
 
381
       </P
 
382
></DD
 
383
><DT
 
384
><TT
 
385
CLASS="FILENAME"
 
386
>test_cpp.cpp</TT
 
387
></DT
 
388
><DD
 
389
><P
 
390
>        The main code for the application, including
 
391
        the <CODE
 
392
CLASS="FUNCTION"
 
393
>main</CODE
 
394
> routine, and in this example a
 
395
        C++ class.
 
396
 
 
397
</P><PRE
 
398
CLASS="PROGRAMLISTING"
 
399
>#include "test_mod.h"
 
400
 
 
401
class TestCpp
 
402
{
 
403
  public:
 
404
    TestCpp();
 
405
    void test();
 
406
    ~TestCpp();
 
407
};
 
408
 
 
409
TestCpp::TestCpp()
 
410
{
 
411
    db_connect();
 
412
}
 
413
 
 
414
void
 
415
TestCpp::test()
 
416
{
 
417
    db_test();
 
418
}
 
419
 
 
420
TestCpp::~TestCpp()
 
421
{
 
422
    db_disconnect();
 
423
}
 
424
 
 
425
int
 
426
main(void)
 
427
{
 
428
    TestCpp *t = new TestCpp();
 
429
 
 
430
    t-&#62;test();
 
431
    return 0;
 
432
}</PRE
 
433
><P>
 
434
       </P
 
435
></DD
 
436
></DL
 
437
></DIV
 
438
><P>
 
439
   </P
 
440
><P
 
441
>    To build the application, proceed as follows.  Convert
 
442
    <TT
 
443
CLASS="FILENAME"
 
444
>test_mod.pgc</TT
 
445
> into <TT
 
446
CLASS="FILENAME"
 
447
>test_mod.c</TT
 
448
> by
 
449
    running <TT
 
450
CLASS="COMMAND"
 
451
>ecpg</TT
 
452
>, and generate
 
453
    <TT
 
454
CLASS="FILENAME"
 
455
>test_mod.o</TT
 
456
> by compiling
 
457
    <TT
 
458
CLASS="FILENAME"
 
459
>test_mod.c</TT
 
460
> with the C compiler:
 
461
</P><PRE
 
462
CLASS="PROGRAMLISTING"
 
463
>ecpg -o test_mod.c test_mod.pgc
 
464
cc -c test_mod.c -o test_mod.o</PRE
 
465
><P>
 
466
   </P
 
467
><P
 
468
>    Next, generate <TT
 
469
CLASS="FILENAME"
 
470
>test_cpp.o</TT
 
471
> by compiling
 
472
    <TT
 
473
CLASS="FILENAME"
 
474
>test_cpp.cpp</TT
 
475
> with the C++ compiler:.
 
476
</P><PRE
 
477
CLASS="PROGRAMLISTING"
 
478
>c++ -c test_cpp.cpp -o test_cpp.o</PRE
 
479
><P>
 
480
   </P
 
481
><P
 
482
>    Finally, link these object files, <TT
 
483
CLASS="FILENAME"
 
484
>test_cpp.o</TT
 
485
>
 
486
    and <TT
 
487
CLASS="FILENAME"
 
488
>test_mod.o</TT
 
489
>, into one executable, using the C++
 
490
    compiler driver:
 
491
</P><PRE
 
492
CLASS="PROGRAMLISTING"
 
493
>c++ test_cpp.o test_mod.o -lecpg -o test_cpp</PRE
 
494
><P>
 
495
   </P
 
496
></DIV
 
497
></DIV
 
498
><DIV
 
499
CLASS="NAVFOOTER"
 
500
><HR
 
501
ALIGN="LEFT"
 
502
WIDTH="100%"><TABLE
 
503
SUMMARY="Footer navigation table"
 
504
WIDTH="100%"
 
505
BORDER="0"
 
506
CELLPADDING="0"
 
507
CELLSPACING="0"
 
508
><TR
 
509
><TD
 
510
WIDTH="33%"
 
511
ALIGN="left"
 
512
VALIGN="top"
 
513
><A
 
514
HREF="ecpg-lo.html"
 
515
ACCESSKEY="P"
 
516
>Prev</A
 
517
></TD
 
518
><TD
 
519
WIDTH="34%"
 
520
ALIGN="center"
 
521
VALIGN="top"
 
522
><A
 
523
HREF="index.html"
 
524
ACCESSKEY="H"
 
525
>Home</A
 
526
></TD
 
527
><TD
 
528
WIDTH="33%"
 
529
ALIGN="right"
 
530
VALIGN="top"
 
531
><A
 
532
HREF="ecpg-sql-commands.html"
 
533
ACCESSKEY="N"
 
534
>Next</A
 
535
></TD
 
536
></TR
 
537
><TR
 
538
><TD
 
539
WIDTH="33%"
 
540
ALIGN="left"
 
541
VALIGN="top"
 
542
>Large Objects</TD
 
543
><TD
 
544
WIDTH="34%"
 
545
ALIGN="center"
 
546
VALIGN="top"
 
547
><A
 
548
HREF="ecpg.html"
 
549
ACCESSKEY="U"
 
550
>Up</A
 
551
></TD
 
552
><TD
 
553
WIDTH="33%"
 
554
ALIGN="right"
 
555
VALIGN="top"
 
556
>Embedded SQL Commands</TD
 
557
></TR
 
558
></TABLE
 
559
></DIV
 
560
></BODY
 
561
></HTML
 
562
>
 
 
b'\\ No newline at end of file'