1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
|
<?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.9. Preprocessor Directives</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-errors.html" title="36.8. Error Handling" /><link rel="next" href="ecpg-process.html" title="36.10. Processing Embedded SQL Programs" /></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.9. Preprocessor Directives</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-errors.html" title="36.8. Error Handling">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 15.7 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-process.html" title="36.10. Processing Embedded SQL Programs">Next</a></td></tr></table><hr /></div><div class="sect1" id="ECPG-PREPROC"><div class="titlepage"><div><div><h2 class="title" style="clear: both">36.9. Preprocessor Directives</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ecpg-preproc.html#ECPG-INCLUDE">36.9.1. Including Files</a></span></dt><dt><span class="sect2"><a href="ecpg-preproc.html#ECPG-DEFINE">36.9.2. The define and undef Directives</a></span></dt><dt><span class="sect2"><a href="ecpg-preproc.html#ECPG-IFDEF">36.9.3. ifdef, ifndef, elif, else, and endif Directives</a></span></dt></dl></div><p>
Several preprocessor directives are available that modify how
the <code class="command">ecpg</code> preprocessor parses and processes a
file.
</p><div class="sect2" id="ECPG-INCLUDE"><div class="titlepage"><div><div><h3 class="title">36.9.1. Including Files</h3></div></div></div><p>
To include an external file into your embedded SQL program, use:
</p><pre class="programlisting">
EXEC SQL INCLUDE <em class="replaceable"><code>filename</code></em>;
EXEC SQL INCLUDE <<em class="replaceable"><code>filename</code></em>>;
EXEC SQL INCLUDE "<em class="replaceable"><code>filename</code></em>";
</pre><p>
The embedded SQL preprocessor will look for a file named
<code class="literal"><em class="replaceable"><code>filename</code></em>.h</code>,
preprocess it, and include it in the resulting C output. Thus,
embedded SQL statements in the included file are handled correctly.
</p><p>
The <code class="command">ecpg</code> preprocessor will search a file at
several directories in following order:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">current directory</li><li class="listitem"><code class="filename">/usr/local/include</code></li><li class="listitem">PostgreSQL include directory, defined at build time (e.g., <code class="filename">/usr/local/pgsql/include</code>)</li><li class="listitem"><code class="filename">/usr/include</code></li></ul></div><p>
But when <code class="literal">EXEC SQL INCLUDE
"<em class="replaceable"><code>filename</code></em>"</code> is used, only the
current directory is searched.
</p><p>
In each directory, the preprocessor will first look for the file
name as given, and if not found will append <code class="literal">.h</code>
to the file name and try again (unless the specified file name
already has that suffix).
</p><p>
Note that <code class="command">EXEC SQL INCLUDE</code> is <span class="emphasis"><em>not</em></span> the same as:
</p><pre class="programlisting">
#include <<em class="replaceable"><code>filename</code></em>.h>
</pre><p>
because this file would not be subject to SQL command preprocessing.
Naturally, you can continue to use the C
<code class="literal">#include</code> directive to include other header
files.
</p><div class="note"><h3 class="title">Note</h3><p>
The include file name is case-sensitive, even though the rest of
the <code class="literal">EXEC SQL INCLUDE</code> command follows the normal
SQL case-sensitivity rules.
</p></div></div><div class="sect2" id="ECPG-DEFINE"><div class="titlepage"><div><div><h3 class="title">36.9.2. The define and undef Directives</h3></div></div></div><p>
Similar to the directive <code class="literal">#define</code> that is known from C,
embedded SQL has a similar concept:
</p><pre class="programlisting">
EXEC SQL DEFINE <em class="replaceable"><code>name</code></em>;
EXEC SQL DEFINE <em class="replaceable"><code>name</code></em> <em class="replaceable"><code>value</code></em>;
</pre><p>
So you can define a name:
</p><pre class="programlisting">
EXEC SQL DEFINE HAVE_FEATURE;
</pre><p>
And you can also define constants:
</p><pre class="programlisting">
EXEC SQL DEFINE MYNUMBER 12;
EXEC SQL DEFINE MYSTRING 'abc';
</pre><p>
Use <code class="literal">undef</code> to remove a previous definition:
</p><pre class="programlisting">
EXEC SQL UNDEF MYNUMBER;
</pre><p>
</p><p>
Of course you can continue to use the C versions <code class="literal">#define</code>
and <code class="literal">#undef</code> in your embedded SQL program. The difference
is where your defined values get evaluated. If you use <code class="literal">EXEC SQL
DEFINE</code> then the <code class="command">ecpg</code> preprocessor evaluates the defines and substitutes
the values. For example if you write:
</p><pre class="programlisting">
EXEC SQL DEFINE MYNUMBER 12;
...
EXEC SQL UPDATE Tbl SET col = MYNUMBER;
</pre><p>
then <code class="command">ecpg</code> will already do the substitution and your C compiler will never
see any name or identifier <code class="literal">MYNUMBER</code>. Note that you cannot use
<code class="literal">#define</code> for a constant that you are going to use in an
embedded SQL query because in this case the embedded SQL precompiler is not
able to see this declaration.
</p><p>
If multiple input files are named on the <code class="command">ecpg</code>
preprocessor's command line, the effects of <code class="literal">EXEC SQL
DEFINE</code> and <code class="literal">EXEC SQL UNDEF</code> do not carry
across files: each file starts with only the symbols defined
by <code class="option">-D</code> switches on the command line.
</p></div><div class="sect2" id="ECPG-IFDEF"><div class="titlepage"><div><div><h3 class="title">36.9.3. ifdef, ifndef, elif, else, and endif Directives</h3></div></div></div><p>
You can use the following directives to compile code sections conditionally:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">EXEC SQL ifdef <em class="replaceable"><code>name</code></em>;</code></span></dt><dd><p>
Checks a <em class="replaceable"><code>name</code></em> and processes subsequent lines if
<em class="replaceable"><code>name</code></em> has been defined via <code class="literal">EXEC SQL define
<em class="replaceable"><code>name</code></em></code>.
</p></dd><dt><span class="term"><code class="literal">EXEC SQL ifndef <em class="replaceable"><code>name</code></em>;</code></span></dt><dd><p>
Checks a <em class="replaceable"><code>name</code></em> and processes subsequent lines if
<em class="replaceable"><code>name</code></em> has <span class="emphasis"><em>not</em></span> been defined via
<code class="literal">EXEC SQL define <em class="replaceable"><code>name</code></em></code>.
</p></dd><dt><span class="term"><code class="literal">EXEC SQL elif <em class="replaceable"><code>name</code></em>;</code></span></dt><dd><p>
Begins an optional alternative section after an
<code class="literal">EXEC SQL ifdef <em class="replaceable"><code>name</code></em></code> or
<code class="literal">EXEC SQL ifndef <em class="replaceable"><code>name</code></em></code>
directive. Any number of <code class="literal">elif</code> sections can appear.
Lines following an <code class="literal">elif</code> will be processed
if <em class="replaceable"><code>name</code></em> has been
defined <span class="emphasis"><em>and</em></span> no previous section of the same
<code class="literal">ifdef</code>/<code class="literal">ifndef</code>...<code class="literal">endif</code>
construct has been processed.
</p></dd><dt><span class="term"><code class="literal">EXEC SQL else;</code></span></dt><dd><p>
Begins an optional, final alternative section after an
<code class="literal">EXEC SQL ifdef <em class="replaceable"><code>name</code></em></code> or
<code class="literal">EXEC SQL ifndef <em class="replaceable"><code>name</code></em></code>
directive. Subsequent lines will be processed if no previous section
of the same
<code class="literal">ifdef</code>/<code class="literal">ifndef</code>...<code class="literal">endif</code>
construct has been processed.
</p></dd><dt><span class="term"><code class="literal">EXEC SQL endif;</code></span></dt><dd><p>
Ends an
<code class="literal">ifdef</code>/<code class="literal">ifndef</code>...<code class="literal">endif</code>
construct. Subsequent lines are processed normally.
</p></dd></dl></div><p>
</p><p>
<code class="literal">ifdef</code>/<code class="literal">ifndef</code>...<code class="literal">endif</code>
constructs can be nested, up to 127 levels deep.
</p><p>
This example will compile exactly one of the three <code class="literal">SET
TIMEZONE</code> commands:
</p><pre class="programlisting">
EXEC SQL ifdef TZVAR;
EXEC SQL SET TIMEZONE TO TZVAR;
EXEC SQL elif TZNAME;
EXEC SQL SET TIMEZONE TO TZNAME;
EXEC SQL else;
EXEC SQL SET TIMEZONE TO 'GMT';
EXEC SQL endif;
</pre><p>
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-errors.html" title="36.8. Error Handling">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="ecpg-process.html" title="36.10. Processing Embedded SQL Programs">Next</a></td></tr><tr><td width="40%" align="left" valign="top">36.8. Error Handling </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.7 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 36.10. Processing Embedded SQL Programs</td></tr></table></div></body></html>
|
