.\" cf. groff_mdoc
.Dd 26 مارس 2015
.Dt BSQLDB 1
.Os FreeTDS 1.5.19
.Sh "نام (NAME)"
.Nm bsqldb
.Nd پردازشگر دسته‌ای اسکریپت SQL با استفاده از DB-Library
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm
.Op Fl hqv
.Op Fl S Ar servername
.Op Fl D Ar database
.Op Fl U Ar username
.Op Fl P Ar password
.Op Fl i Ar input_file
.Op Fl o Ar output_file
.Op Fl e Ar error_file
.Op Fl H Ar hostname
.Op Fl t Ar field_term
.Op Fl R Ar pivot_description
.\"
.Sh "توضیحات (DESCRIPTION)"
.Nm
یک برنامه کمکی است که به همراه FreeTDS عرضه می‌شود.
.Nm
معادل غیرتعاملی برنامه‌های کمکی «isql» است که توسط Sybase و Microsoft منتشر شده‌اند. مانند آن‌ها،
.Nm
از دستور «go» در یک خط مجزا به عنوان جداکننده بین دسته‌ها (batchها) استفاده می‌کند. نیازی نیست که پس از آخرین دسته، دستور «go» قرار گیرد.
.Nm
از رابط برنامه‌نویسی DB-Library ارائه‌شده توسط FreeTDS بهره می‌برد. این API بدون شک برای توسعه‌دهندگان برنامه‌های کاربردی نیز در دسترس است.
.Sh "گزینه‌ها (OPTIONS)"
.Bl -tag -width indent
.It Fl D Ar database
پایگاه داده مورد استفاده.
.It Fl H Ar hostname
نام کلاینت (hostname) ارسالی به سرور را بازنویسی می‌کند.
.It Fl P Ar password
گذرواژه سرور پایگاه داده.
.It Fl S Ar servername
سرور پایگاه داده برای اتصال.
.It Fl U Ar username
نام کاربری ورود به سرور پایگاه داده. اگر نام کاربری ارائه نشود، برای اتصالات TDS 7+ تلاش می‌شود تا از ورود مبتنی بر دامنه (domain login) استفاده شود.
.It Fl e Ar error_file
نام فایل برای ثبت خطاها.
.It Fl h
چاپ سرستون‌ها به همراه داده‌ها در همان فایل.
.It Fl i Ar input_file
نام فایل اسکریپت حاوی دستورهای SQL.
.It Fl o Ar output_file
نام فایل خروجی، برای نگهداری داده‌های نتیجه.
.It Fl q
متاداده‌های ستون، وضعیت بازگشتی یا تعداد ردیف‌ها چاپ نشود. این گزینه
.Fl h
را بی‌اثر می‌کند.
.It Fl t Ar field_term
جداکننده فیلد را مشخص می‌کند. مقدار پیش‌فرض دو فاصله (' ') است. دنباله‌های گریز شناخته‌شده عبارتند از تب ('\\t')، بازگشت به ابتدای سطر ('\\r')، خط جدید ('\\n') و بک‌اسلش ('\\\\').
.It Fl v
حالت پرگو (verbose)، برای ارائه اطلاعات بیشتر درباره تعاملات DB-Library. این حالت همچنین فراداده‌های مجموعه نتایج، از جمله کدهای بازگشتی را گزارش می‌دهد. تمام داده‌های این حالت در خطای استاندارد (یا
.Fl e Ns )
نوشته می‌شوند تا تداخلی با جریان داده‌ها نداشته باشند.
.It Fl R Ar pivot_description
مشخص کردن تبدیل پیوت (pivot transformation). قالب آن به صورت
.Ao Ar down\ columns Ac
.Ao Ar across\ columns Ac
.Ao Ar function Ac
.Ao Ar value Ac
است.
ستون‌ها با شماره مشخص می‌شوند.
قالب
.Ar down columns
و
.Ar across columns
فهرستی از ستون‌ها است که با کاما از یکدیگر جدا شده‌اند.
مقدار
.Ar function
یکی از موارد count ،sum ،min یا max است.
.El
.\"
.Sh "محیط (ENVIRONMENT)"
.Ev DSQUERY
مقدار پیش‌فرض
.Ar servername
.\"
.Sh "نکات (NOTES)"
.Nm
یک فیلتر است؛ داده‌ها را از ورودی استاندارد می‌خواند، در خروجی استاندارد می‌نویسد و خطاها را در خطای استاندارد ثبت می‌کند. گزینه‌های
.Fl i Ns ،
.Fl o
و
.Fl e
این مقادیر پیش‌فرض را لغو می‌کنند.
.Pp
کد منبع
.Nm
به عنوان الگویی برای کاربران DB-Library طراحی شده است. DB-Library مجموعه غنی و کاملی از توابع دارد و گاهی ممکن است درک نحوه استفاده از آن‌ها، به‌ویژه در دفعات اول، دشوار باشد. اگر نکته‌ای در کد منبع برای شما مبهم است، تشویق می‌شوید که نظرات خود را از طریق ایمیل برای نویسنده ارسال کنید.
.\"
.Sh "وضعیت خروج (EXIT STATUS)"
.Nm
در صورت موفقیت مقدار 0، و در صورتی که سرور نتواند پرس‌وجو را پردازش کند مقداری بزرگ‌تر از صفر (>0) برمی‌گرداند.
.Pp
برای پیام‌هایی با سطح اهمیت (severity) بیشتر از 10،
.Nm
تابع exit(3) را با همان سطح اهمیت فراخوانی می‌کند. برای نمونه، اگر سطح اهمیت 16 باشد،
.Nm
کد وضعیت خروج 16 را به شل برمی‌گرداند.
.\"
.Sh "تاریخچه (HISTORY)"
.Nm
نخستین بار در FreeTDS 0.63 ارائه شد.
.\"
.Sh "نویسندگان (AUTHORS)"
ابزار
.Nm
توسط
.An "James K. Lowden" Aq jklowden@freetds.org
نوشته شده است.
.\"
.Sh "گزارش باگ‌ها (BUGS)"
سرورهای مایکروسافت از SQL Server 7.0 SP 3 به بعد، پارامترهای خروجی (output parameters) را برنمی‌گردانند مگر آنکه از توابع RPC استفاده شود. این بدان معناست که
.Nm
نمی‌تواند پارامترهای خروجی را برای روال‌های ذخیره‌شده (stored procedures) در این سرورها برگرداند.