'\" t
.\"     Title: ecpg
.\"    Author: The PostgreSQL Global Development Group
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net>
.\"      Date: 2026
.\"    Manual: PostgreSQL 18.6 Documentation
.\"    Source: PostgreSQL 18.6
.\"  Language: English
.\"
.TH "ECPG" "1" "2026" "PostgreSQL 18.6" "PostgreSQL 18.6 Documentation"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "نام (NAME)"
ecpg \- پیش‌پردازندهٔ C برای SQL تعبیه‌شده
.SH "خلاصه دستور (SYNOPSIS)"
.HP \w'\fBecpg\fR\ 'u
\fBecpg\fR [\fIoption\fR...] \fIfile\fR...
.SH "توضیحات (DESCRIPTION)"
.PP
\fBecpg\fR
پیش‌پردازندهٔ SQL تعبیه‌شده (embedded SQL) برای برنامه‌های C است\&. این ابزار برنامه‌های C حاوی دستورات تعبیه‌شدهٔ SQL را با جایگزین کردن فراخوانی‌های SQL با فراخوانی‌های توابع خاص، به کد عادی C تبدیل می‌کند\&. سپس فایل‌های خروجی می‌توانند با هر زنجیره ابزار کامپایلر C پردازش شوند\&.
.PP
\fBecpg\fR
هر فایل ورودی مشخص‌شده در خط فرمان را به فایل خروجی C متناظر تبدیل می‌کند\&. اگر نام یک فایل ورودی پسوندی نداشته باشد، پسوند
\&.pgc
در نظر گرفته می‌شود\&. برای ایجاد نام فایل خروجی، پسوند فایل با
\&.c
جایگزین خواهد شد\&. با این حال، می‌توان نام فایل خروجی را با استفاده از گزینهٔ
\fB\-o\fR
تغییر داد\&.
.PP
اگر نام فایل ورودی صرفاً
\-
باشد،
\fBecpg\fR
برنامه را از ورودی استاندارد می‌خواند (و در خروجی استاندارد می‌نویسد، مگر اینکه با
\fB\-o\fR
تغییر داده شود)\&.
.PP
این صفحهٔ راهنما زبان تعبیه‌شدهٔ SQL را توصیف نمی‌کند\&. برای اطلاعات بیشتر در این رابطه،
فصل\ \&34
را ببینید\&.
.SH "گزینه‌ها (OPTIONS)"
.PP
\fBecpg\fR
آرگومان‌های خط فرمان زیر را می‌پذیرد:
.PP
\fB\-c\fR
.RS 4
تولید خودکار کدهای خاص C از کدهای SQL\&. در حال حاضر، این قابلیت برای
EXEC SQL TYPE
کار می‌کند\&.
.RE
.PP
\fB\-C \fR\fB\fImode\fR\fR
.RS 4
تعیین حالت سازگاری\&.
\fImode\fR
می‌تواند
INFORMIX،
INFORMIX_SE
یا
ORACLE
باشد\&.
.RE
.PP
\fB\-D \fR\fB\fIsymbol\fR\fR\fB[=\fR\fB\fIvalue\fR\fR\fB]\fR
.RS 4
تعریف یک نماد پیش‌پردازنده، معادل با دستورالعمل
\fBEXEC SQL DEFINE\fR\&.
اگر هیچ مقداری (\fIvalue\fR)
مشخص نشود، نماد با مقدار
1
تعریف می‌شود\&.
.RE
.PP
\fB\-h\fR
.RS 4
پردازش فایل‌های سرایند (header)\&. هنگامی که این گزینه مشخص شود، پسوند فایل خروجی به‌جای
\&.c
به
\&.h
تبدیل می‌شود و پسوند پیش‌فرض فایل ورودی به‌جای
\&.pgc
برابر با
\&.pgh
خواهد بود\&. همچنین، گزینهٔ
\fB\-c\fR
اجباراً فعال می‌شود\&.
.RE
.PP
\fB\-i\fR
.RS 4
تجزیه فایل‌های سرایند سیستمی (system include files) نیز انجام شود\&.
.RE
.PP
\fB\-I \fR\fB\fIdirectory\fR\fR
.RS 4
مشخص کردن یک مسیر include اضافی، که برای یافتن فایل‌های ضمیمه‌شده از طریق
EXEC SQL INCLUDE
استفاده می‌شود\&. مقادیر پیش‌فرض به ترتیب عبارتند از:
\&.
(دایرکتوری جاری)،
/usr/local/include،
دایرکتوری include مربوط به
PostgreSQL
که هنگام کامپایل تعریف شده است (پیش‌فرض:
/usr/local/pgsql/include)،
و
/usr/include\&.
.RE
.PP
\fB\-o \fR\fB\fIfilename\fR\fR
.RS 4
مشخص می‌کند که
\fBecpg\fR
باید تمام خروجی خود را در
\fIfilename\fR
داده‌شده بنویسد\&. برای ارسال تمام خروجی به خروجی استاندارد، از
\-o \-
استفاده کنید\&.
.RE
.PP
\fB\-r \fR\fB\fIoption\fR\fR
.RS 4
انتخاب رفتار زمان اجرا (run\-time)\&.
\fIOption\fR
می‌تواند یکی از موارد زیر باشد:
.PP
\fBno_indicator\fR
.RS 4
عدم استفاده از نشانگرها (indicators) و در عوض استفاده از مقادیر خاص برای نمایش مقادیر null\&. از لحاظ تاریخی پایگاه‌های داده‌ای وجود داشته‌اند که از این روش استفاده می‌کردند\&.
.RE
.PP
\fBprepare\fR
.RS 4
آماده‌سازی (prepare) تمام دستورات پیش از استفاده از آن‌ها\&. کتابخانهٔ libecpg یک حافظهٔ پنهان (cache) از دستورات آماده‌شده نگه می‌دارد و در صورت اجرای مجدد یک دستور، از آن دوباره استفاده می‌کند\&. اگر حافظهٔ پنهان پر شود، libecpg دستوری را که کمتر از همه استفاده شده است آزاد خواهد کرد\&.
.RE
.PP
\fBquestionmarks\fR
.RS 4
مجاز دانستن علامت سؤال به عنوان جای‌نگهدار (placeholder) به دلایل سازگاری\&. در گذشته‌های دور، این حالت پیش‌فرض بود\&.
.RE
.RE
.PP
\fB\-t\fR
.RS 4
روشن کردن ثبت خودکار (autocommit) تراکنش‌ها\&. در این حالت، هر دستور SQL به‌طور خودکار ثبت (commit) می‌شود مگر اینکه درون یک بلوک صریح تراکنش قرار داشته باشد\&. در حالت پیش‌فرض، دستورات تنها زمانی ثبت می‌شوند که
\fBEXEC SQL COMMIT\fR
صادر شود\&.
.RE
.PP
\fB\-v\fR
.RS 4
چاپ اطلاعات تکمیلی شامل نسخه و مسیر include\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
چاپ نسخهٔ
ecpg
و خروج\&.
.RE
.PP
\fB\-?\fR
.br
\fB\-\-help\fR
.RS 4
نمایش راهنما دربارهٔ آرگومان‌های خط فرمان
ecpg
و خروج\&.
.RE
.SH "نکات (NOTES)"
.PP
هنگام کامپایل فایل‌های کد C پیش‌پردازش‌شده، کامپایلر باید قادر باشد فایل‌های سرایند
ECPG
را در دایرکتوری include مربوط به
PostgreSQL
پیدا کند\&. بنابراین، ممکن است مجبور باشید هنگام فراخوانی کامپایلر از گزینهٔ
\fB\-I\fR
استفاده کنید (برای مثال،
\-I/usr/local/pgsql/include)\&.
.PP
برنامه‌هایی که از کد C حاوی SQL تعبیه‌شده استفاده می‌کنند باید با کتابخانهٔ
libecpg
پیوند (link) داده شوند؛ برای مثال با استفاده از گزینه‌های پیونددهندهٔ
\-L/usr/local/pgsql/lib \-lecpg\&.
.PP
مسیر مناسب هر یک از این دایرکتوری‌ها برای نصب مورد نظر را می‌توان با استفاده از
\fBpg_config\fR(1)
به دست آورد\&.
.SH "مثال‌ها (EXAMPLES)"
.PP
اگر یک فایل منبع C حاوی SQL تعبیه‌شده با نام
prog1\&.pgc
دارید، می‌توانید با استفاده از توالی دستورات زیر یک برنامهٔ اجرایی بسازید:
.sp
.if n \{\
.RS 4
.\}
.nf
ecpg prog1\&.pgc
cc \-I/usr/local/pgsql/include \-c prog1\&.c
cc \-o prog1 prog1\&.o \-L/usr/local/pgsql/lib \-lecpg
.fi
.if n \{\
.RE
.\}