.\" cf. groff_mdoc
.Dd March 25, 2015
.Os FreeTDS 1.5.19
.Dt FREEBCP 1
.Sh "نام (NAME)"
.Nm freebcp
.Nd ابزار بارگذاری دسته‌ای داده‌ها برای پایگاه‌های داده Sybase و Microsoft
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm
.Bo Bo Ao Ar database Ac Ns . Bc Ns Ao Ar owner Ac Ns . Bc Ns Aq Ar object_name
.Bro
.Ar in
|
.Ar [query] Ns Ar out
.Brc
.Ar datafile
.Bro
.Fl c
|
.Fl n
|
.Fl f Ar formatfile
.Brc
.Op Fl S Ar servername
.Op Fl D Ar dbname
.Op Fl U Ar username
.Op Fl P Ar password
.Op Fl b Ar batchsize
.Op Fl F Ar firstrow
.Op Fl L Ar lastrow
.Op Fl e Ar errfile
.Op Fl I Ar interfaces
.Op Fl m Ar maxerror
.Op Fl t Ar field_term
.Op Fl r Ar row_term
.Op Fl h Ar hints
.Op Fl T Ar textsize
.Op Fl A Ar packet_size
.Op Fl O Ar options
.Op Fl i Ar inputfile
.Op Fl o Ar outputfile
.Op Fl C Ar charset
.Op Fl EdVv
.\"
.Sh "توضیحات (DESCRIPTION)"
.Nm
ابزاری کاربردی است که به همراه FreeTDS توزیع می‌شود.
.Nm
عملکرد ابزارهای bcp توزیع‌شده توسط Sybase و Microsoft را (حداقل تا حدی) شبیه‌سازی و پیاده‌سازی می‌کند.
.Nm
از رابط برنامه‌نویسی کاربردی (API) مربوط به DB-Library bcp که توسط FreeTDS ارائه شده است استفاده می‌کند. این API برای توسعه‌دهندگان نرم‌افزار نیز در دسترس است.
.Pp
برای اطلاعات دقیق‌تر درباره عملکرد bcp، می‌توان به صفحات راهنما یا راهنمای برخط Sybase یا SQL Server مراجعه کرد.
.\"
.Sh "جدول‌ها و فایل‌ها (TABLES AND FILES)"
.Bl -tag -width indent
.It Ar database
نام پایگاه داده‌ای که شیء مورد نظر برای کپی در آن قرار دارد. در صورتی که جدول یا نما (view) در پایگاه داده پیش‌فرض برای
.Ar username
باشد، اختیاری است.
.It Ar schema
طرح‌واره (schema) شیء مورد کپی. اگر مشخص نشود، طرح‌واره پیش‌فرض برای
.Ar username
استفاده می‌شود.
.It Ar object
نام شیء پایگاه داده‌ای که می‌خواهید به آن دسترسی داشته باشید، معمولاً یک جدول. این شیء می‌تواند یک نما (view) نیز باشد. همه نماها قابل خواندن هستند؛ برخی از آن‌ها نیز تحت قیود خاصی قابل نوشتن می‌باشند. به همراه
.Ar queryout Ns ، Ar object
می‌تواند یک پرس‌وجوی SQL نیز باشد.
.It Ar in
کپی داده‌ها از یک فایل میزبان به جدول پایگاه داده.
.It Ar out
کپی داده‌ها از یک جدول پایگاه داده به یک فایل میزبان.
.It Ar queryout
نشان می‌دهد که
.Ar table_name
در واقع یک عبارت SQL است، نه یک شیء پایگاه داده.
.Nm
این پرس‌وجو را اجرا کرده و نتایج را در یک فایل می‌نویسد. (بهتر است که پرس‌وجو یک و فقط یک مجموعه نتیجه بازگرداند.)
.It Ar datafile
نام یک فایل در سیستم‌عامل.
.El
.\"
.Sh "گزینه‌ها (OPTIONS)"
.Bl -tag -width indent
.It Fl A Ar packet_size
تنظیم اندازه بسته TDS به packet_size. دلیل مشخصی برای انجام این کار وجود ندارد، مگر برای آزمایش و تجربه.
.It Fl D Ar dbname
نام پایگاه داده پیش‌فرضی که باید استفاده شود. پایگاه داده پیش‌فرض مرتبط با حساب کاربری ورود را نادیده می‌گیرد. باعث می‌شود
.Nm
بلافاصله پس از ورود به سیستم و پیش از آغاز عملیات BCP، یک دستور
.Ic USE Ar dbname
صادر کند.
.It Fl E
نوشتن داده‌های موجود در datafile در ستون IDENTITY جدول. بدون این فلگ، داده‌های هویت موجود در datafile نادیده گرفته شده و مقادیر جدید IDENTITY برای سطرهای واردشده تولید می‌شوند.
.It Fl F Ar firstrow
نخستین سطری که باید از فایل ورودی یا جدول پایگاه داده کپی شود. مقدار پیش‌فرض سطر اول، یعنی سطر 1 است.
.It Fl I Ar interfaces
نام و مسیر فایل
.Pa interfaces
برای جستجو هنگام اتصال به servername. بر تنظیمات
.Pa freetds.conf
ارجحیت دارد.
.It Fl L Ar lastrow
آخرین سطری که باید از یک فایل ورودی یا جدول پایگاه داده کپی شود. مقدار پیش‌فرض آخرین سطر است.
.It Fl O Ar options
متن SQL برای تنظیم گزینه‌های اتصال پیش از عملیات bcp. اگر
.Ar options
یک نام فایل معتبر باشد، دستورات SQL از فایل خوانده می‌شوند. گاهی اوقات برای
.Ar queryout
مورد نیاز است.
مثال:
.Li -O `SET QUOTED_IDENTIFIER ON' Ns .
.It Fl P Ar password
گذرواژه مرتبط با
.Ar username Ns .
.It Fl S Ar servername
نام سرور پایگاه داده‌ای که باید به آن متصل شوید.
.It Fl T Ar textsize
برای ستون‌های متنی یا تصویری، حداکثر تعداد نویسه‌های درخواستی از سرور را تعیین می‌کند. مقدار پیش‌فرض به تنظیمات در
.Pa freetds.conf
بستگی دارد. اگر در هیچ جا مشخص نشده باشد، به طور پیش‌فرض اندازه کامل داده در نظر گرفته می‌شود.
.It Fl U Ar username
نام کاربری ورود به پایگاه داده. برای اتصالات TDS\ 7+، در صورتی که
.Ar username
مشخص نشده باشد، تلاش برای ورود از طریق دامنه (domain login) انجام می‌گیرد.
.It Fl b Ar batchsize
تعداد سطرها در هر دسته از داده‌های کپی‌شده. دسته‌بندی تنها زمانی اعمال می‌شود که عملیات بارگذاری دسته‌ای به داخل پایگاه داده انجام گیرد. هر دسته از داده‌ها عملاً در پایگاه داده
.Dq commit
می‌شود. مقدار پیش‌فرض برای
.Ar batchsize
برابر با 1000 است.
.It Fl c
فایل داده میزبان در قالب «نویسه‌ای» (character) است (یا خواهد بود)، یعنی یک فایل متنی. کدگذاری با مشخصه charset کلاینت در
.Pa freetds.conf
تعیین می‌شود.
.It Fl d
غیرفعال کردن هرگونه ثبت گزارش (لاگ‌گیری). (شاید کمی غیرمنتظره باشد.)
.It Fl e Ar errfile
نوشتن خطاها در
.Ar errfile Ns .
برای بارگذاری داده‌ها. شامل اطلاعات سطر و ستون و همچنین داده‌های سطر است.
.It Fl f Ar formatfile
قالب فایل داده میزبان توسط
.Ar formatfile
توصیف می‌شود. چیدمان
.Ar formatfile
دقیقاً همانند چیزی است که توسط ابزارهای bcp در Sybase و Microsoft فهمیده می‌شود، اما پیچیده‌تر از آن است که در اینجا توضیح داده شود.
.It Fl h Ar hints
تنظیم راهنماهای bcp (یا bcp hints). برای مقادیر معتبر، به
.Fn bcp_options
در راهنمای مرجع FreeTDS مراجعه فرمایید.
.It Fl m Ar maxerror
توقف پس از برخورد با
.Ar maxerror
خطا. مقدار پیش‌فرض 10 است.
.It Fl n
فایل داده میزبان در قالب «بومی» (
.Dq native Ns
) است. این قالبی است که
.Nm
قادر به پردازش آن است، اما قابل حمل یا قابل خواندن برای انسان نیست.
.It Fl r Ar row_term
پایان‌دهنده سطر برای یک فایل نویسه‌ای. می‌تواند بیش از یک نویسه باشد. مقدار پیش‌فرض نویسه خط جدید ('\\n') است. به گزینه
.Fl c Ns
در بالا مراجعه کنید.
.It Fl t Ar field_term
پایان‌دهنده فیلد برای فایل نویسه‌ای. همچنین به عنوان جداکننده ستون شناخته می‌شود. می‌تواند بیش از یک نویسه باشد. مقدار پیش‌فرض نویسه تب ('\\t') است. به گزینه
.Fl c Ns
در بالا مراجعه کنید.
.It Fl v
.It Fl V
چاپ اطلاعات نسخه و خروج.
.It Fl i Ar inputfile
خواندن داده‌های ورودی از فایل مشخص‌شده.
.It Fl o Ar outputfile
نوشتن داده‌های خروجی در فایل مشخص‌شده.
.It Fl C Ar charset
مشخص کردن مجموعه نویسه‌ها (character set) برای ارتباط با سرور.
.El
.Sh "محیط (ENVIRONMENT)"
.Ev DSQUERY
پیش‌فرض برای
.Ar servername
.\"
.Sh "نکات (NOTES)"
هنگام اتصال به یک سرور پایگاه داده Sybase، استفاده از پروتکل TDS 5.0 الزامی است. هنگام اتصال به سرور پایگاه داده Microsoft SQL Server 2000، پروتکل TDS\ 7 (یا بالاتر) مورد نیاز است.
.Pp
شرکت‌های Sybase و Microsoft نگارش‌های متفاوتی از بخش bcp پروتکل TDS 4.2 را تعریف کرده‌اند. از آنجا که FreeTDS راهی برای تشخیص نوع سرور متصل‌شده ندارد،
.Nm
از نسخه 4.2 پروتکل TDS پشتیبانی نمی‌کند.
.\"
.Sh "تاریخچه (HISTORY)"
.Nm
نخستین بار در FreeTDS 0.60 ظاهر شد.
.Sh "نویسندگان (AUTHORS)"
ابزار
.Nm
توسط
.An Bill Thompson Aq thompbil@exchange.uk.ml.com
نوشته شده است.
.Sh "اشکالات (BUGS)"
در حال حاضر هیچ پشتیبانی از انواع داده‌های متنی (text data types) در
.Nm
هنگامی که SQL Server 2000 سرور هدف باشد وجود ندارد.