begriffs open source - ai-pg/blob - full-docs/man1/ecpg.1

   1 '\" t
   2 .\"     Title: ecpg
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "ECPG" "1" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 ecpg \- embedded SQL C preprocessor
  32 .SH "SYNOPSIS"
  33 .HP \w'\fBecpg\fR\ 'u
  34 \fBecpg\fR [\fIoption\fR...] \fIfile\fR...
  35 .SH "DESCRIPTION"
  36 .PP
  37 \fBecpg\fR
  38 is the embedded SQL preprocessor for C programs\&. It converts C programs with embedded SQL statements to normal C code by replacing the SQL invocations with special function calls\&. The output files can then be processed with any C compiler tool chain\&.
  39 .PP
  40 \fBecpg\fR
  41 will convert each input file given on the command line to the corresponding C output file\&. If an input file name does not have any extension,
  42 \&.pgc
  43 is assumed\&. The file\*(Aqs extension will be replaced by
  44 \&.c
  45 to construct the output file name\&. But the output file name can be overridden using the
  46 \fB\-o\fR
  47 option\&.
  48 .PP
  49 If an input file name is just
  50 \-,
  51 \fBecpg\fR
  52 reads the program from standard input (and writes to standard output, unless that is overridden with
  53 \fB\-o\fR)\&.
  54 .PP
  55 This reference page does not describe the embedded SQL language\&. See
  56 Chapter\ \&34
  57 for more information on that topic\&.
  58 .SH "OPTIONS"
  59 .PP
  60 \fBecpg\fR
  61 accepts the following command\-line arguments:
  62 .PP
  63 \fB\-c\fR
  64 .RS 4
  65 Automatically generate certain C code from SQL code\&. Currently, this works for
  66 EXEC SQL TYPE\&.
  67 .RE
  68 .PP
  69 \fB\-C \fR\fB\fImode\fR\fR
  70 .RS 4
  71 Set a compatibility mode\&.
  72 \fImode\fR
  73 can be
  74 INFORMIX,
  75 INFORMIX_SE, or
  76 ORACLE\&.
  77 .RE
  78 .PP
  79 \fB\-D \fR\fB\fIsymbol\fR\fR\fB[=\fR\fB\fIvalue\fR\fR\fB]\fR
  80 .RS 4
  81 Define a preprocessor symbol, equivalently to the
  82 \fBEXEC SQL DEFINE\fR
  83 directive\&. If no
  84 \fIvalue\fR
  85 is specified, the symbol is defined with the value
  86 1\&.
  87 .RE
  88 .PP
  89 \fB\-h\fR
  90 .RS 4
  91 Process header files\&. When this option is specified, the output file extension becomes
  92 \&.h
  93 not
  94 \&.c, and the default input file extension is
  95 \&.pgh
  96 not
  97 \&.pgc\&. Also, the
  98 \fB\-c\fR
  99 option is forced on\&.
 100 .RE
 101 .PP
 102 \fB\-i\fR
 103 .RS 4
 104 Parse system include files as well\&.
 105 .RE
 106 .PP
 107 \fB\-I \fR\fB\fIdirectory\fR\fR
 108 .RS 4
 109 Specify an additional include path, used to find files included via
 110 EXEC SQL INCLUDE\&. Defaults are
 111 \&.
 112 (current directory),
 113 /usr/local/include, the
 114 PostgreSQL
 115 include directory which is defined at compile time (default:
 116 /usr/local/pgsql/include), and
 117 /usr/include, in that order\&.
 118 .RE
 119 .PP
 120 \fB\-o \fR\fB\fIfilename\fR\fR
 121 .RS 4
 122 Specifies that
 123 \fBecpg\fR
 124 should write all its output to the given
 125 \fIfilename\fR\&. Write
 126 \-o \-
 127 to send all output to standard output\&.
 128 .RE
 129 .PP
 130 \fB\-r \fR\fB\fIoption\fR\fR
 131 .RS 4
 132 Selects run\-time behavior\&.
 133 \fIOption\fR
 134 can be one of the following:
 135 .PP
 136 \fBno_indicator\fR
 137 .RS 4
 138 Do not use indicators but instead use special values to represent null values\&. Historically there have been databases using this approach\&.
 139 .RE
 140 .PP
 141 \fBprepare\fR
 142 .RS 4
 143 Prepare all statements before using them\&. Libecpg will keep a cache of prepared statements and reuse a statement if it gets executed again\&. If the cache runs full, libecpg will free the least used statement\&.
 144 .RE
 145 .PP
 146 \fBquestionmarks\fR
 147 .RS 4
 148 Allow question mark as placeholder for compatibility reasons\&. This used to be the default long ago\&.
 149 .RE
 150 .RE
 151 .PP
 152 \fB\-t\fR
 153 .RS 4
 154 Turn on autocommit of transactions\&. In this mode, each SQL command is automatically committed unless it is inside an explicit transaction block\&. In the default mode, commands are committed only when
 155 \fBEXEC SQL COMMIT\fR
 156 is issued\&.
 157 .RE
 158 .PP
 159 \fB\-v\fR
 160 .RS 4
 161 Print additional information including the version and the "include" path\&.
 162 .RE
 163 .PP
 164 \fB\-\-version\fR
 165 .RS 4
 166 Print the
 167 ecpg
 168 version and exit\&.
 169 .RE
 170 .PP
 171 \fB\-?\fR
 172 .br
 173 \fB\-\-help\fR
 174 .RS 4
 175 Show help about
 176 ecpg
 177 command line arguments, and exit\&.
 178 .RE
 179 .SH "NOTES"
 180 .PP
 181 When compiling the preprocessed C code files, the compiler needs to be able to find the
 182 ECPG
 183 header files in the
 184 PostgreSQL
 185 include directory\&. Therefore, you might have to use the
 186 \fB\-I\fR
 187 option when invoking the compiler (e\&.g\&.,
 188 \-I/usr/local/pgsql/include)\&.
 189 .PP
 190 Programs using C code with embedded SQL have to be linked against the
 191 libecpg
 192 library, for example using the linker options
 193 \-L/usr/local/pgsql/lib \-lecpg\&.
 194 .PP
 195 The value of either of these directories that is appropriate for the installation can be found out using
 196 \fBpg_config\fR(1)\&.
 197 .SH "EXAMPLES"
 198 .PP
 199 If you have an embedded SQL C source file named
 200 prog1\&.pgc, you can create an executable program using the following sequence of commands:
 201 .sp
 202 .if n \{\
 203 .RS 4
 204 .\}
 205 .nf
 206 ecpg prog1\&.pgc
 207 cc \-I/usr/local/pgsql/include \-c prog1\&.c
 208 cc \-o prog1 prog1\&.o \-L/usr/local/pgsql/lib \-lecpg
 209 .fi
 210 .if n \{\
 211 .RE
 212 .\}
 213