.\" $Header: /upc/share/CVS/netcdf-3/ncgen3/ncgen3.1,v 1.1 2009/09/24 18:19:10 dmh Exp $
.TH NCGEN3 1 "$Date: 2009/09/24 18:19:10 $" "Printed: \n(yr-\n(mo-\n(dy" "UNIDATA UTILITIES"
.SH "نام (NAME)"
ncgen3 \- تولید فایل netCDF کلاسیک یا ۶۴ بیتی کلاسیک، برنامه C یا برنامه Fortran از روی فایل CDL
.SH "خلاصه دستور (SYNOPSIS)"
.HP
ncgen3
.nh
\%[\-b]
\%[\-c]
\%[\-f]
\%[\-k \fIkind_of_file\fP]
\%[\-x]
\%[\-n]
\%[\-o \fInetcdf_filename\fP]
\%\fIinput_file\fP
.hy
.ft
.SH "توضیحات (DESCRIPTION)"
دستور \fBncgen3\fP یک فایل netCDF، یا کد منبع C یا Fortran را برای ایجاد یک فایل netCDF تولید می‌کند. ورودی \fBncgen3\fP توصیفی از یک فایل netCDF در یک زبان کوچک به نام CDL (کوتاه‌شده‌ی network Common Data form Language) است که در ادامه شرح داده شده است.
اگر هیچ گزینه‌ای هنگام فراخوانی \fBncgen3\fP مشخص نشود، صرفاً نحو فایل CDL ورودی را بررسی کرده و در صورت وجود هرگونه نقض نحو CDL، پیام‌های خطا تولید می‌کند. سایر گزینه‌ها را می‌توان برای ایجاد فایل netCDF متناظر، تولید یک برنامه C که از رابط C مربوط به netCDF برای ایجاد فایل netCDF استفاده می‌کند، یا تولید یک برنامه Fortran که از رابط Fortran مربوط به netCDF برای ایجاد همان فایل netCDF بهره می‌برد، به کار گرفت.
.LP
می‌توان \fBncgen3\fP را همراه با برنامه مکمل \fBncdump\fP برای انجام برخی کارهای ساده روی فایل‌های netCDF استفاده کرد. به عنوان مثال، برای تغییر نام یک بُعد در یک فایل netCDF، از \fBncdump\fP برای دریافت نسخه CDL از فایل netCDF استفاده کنید، فایل CDL را برای تغییر نام ابعاد ویرایش نمایید، و از \fBncgen3\fP برای تولید فایل netCDF متناظر از فایل CDL ویرایش‌شده بهره ببرید.
.SH "گزینه‌ها (OPTIONS)"
.IP "\fB-b\fP"
ایجاد یک فایل netCDF (دودویی). در صورت عدم وجود گزینه \fB-o\fP، نام فایل پیش‌فرض از روی نام netCDF (که بعد از کلیدواژه \fBnetcdf\fP در ورودی مشخص شده است) با افزودن پسوند `.nc' ساخته می‌شود. اگر فایلی با نام مشخص‌شده از قبل وجود داشته باشد، رونویسی خواهد شد.
.IP "\fB-c\fP"
تولید کد منبع
.B C
که یک فایل netCDF منطبق با مشخصات netCDF ایجاد می‌کند. کد منبع C در خروجی استاندارد نوشته می‌شود.
.IP "\fB-f\fP"
تولید کد منبع
.B Fortran
که یک فایل netCDF منطبق با مشخصات netCDF ایجاد می‌کند. کد منبع Fortran در خروجی استاندارد نوشته می‌شود.
.IP "\fB-o\fP \fRnetcdf_file\fP"
نام فایل netCDF دودویی ایجادشده. تعیین این گزینه به معنای اعمال گزینه "\fB-b\fP" نیز هست. (این گزینه ضروری است چرا که فایل‌های netCDF را نمی‌توان مستقیماً در خروجی استاندارد نوشت، زیرا خروجی استاندارد قابلیت seek یا پیمایش تصادفی ندارد.)
.IP "\fB-k \fRkind_of_file\fP"
استفاده از \-k2 یا \-k "64-bit offset" مشخص می‌کند که فایل (یا برنامه) تولیدشده باید از نسخه ۲ قالب که از آفست‌های فایل ۶۴ بیتی استفاده می‌کند، بهره گیرد. پیش‌فرض استفاده از قالب نسخه ۱ ("classic") با آفست‌های ۳۲ بیتی فایل است، اگرچه این کار اندازه فایل netCDF، متغیرها و رکوردها را به اندازه‌های پشتیبانی‌شده توسط قالب کلاسیک محدود می‌کند. (NetCDF-4 از انواع دیگری از فایل‌های netCDF شامل "netCDF-4" و "netCDF-4 classic model" نیز پشتیبانی خواهد کرد.)
نکته: جهت سازگاری رو به عقب، \-v نیز به همان معنای \-k پذیرفته می‌شود، اما استفاده از \-k ارجح است تا با گزینه متناظر در ncdump مطابقت داشته باشد.
.IP "\fB-x\fP"
داده‌ها با مقادیر پرکننده (fill values) مقداردهی اولیه نشوند. این کار می‌تواند سرعت ایجاد فایل‌های بزرگ netCDF را تا حد زیادی افزایش دهد، اما تلاش‌های بعدی برای خواندن داده‌های نوشته‌نشده از فایل تولیدشده به‌سادگی قابل تشخیص نخواهد بود.
.SH "مثال‌ها (EXAMPLES)"
.LP
بررسی نحو فایل CDL با نام `\fBfoo.cdl\fP':
.RS
.HP
ncgen3 foo.cdl
.RE
.LP
تولید یک فایل netCDF دودویی معادل با نام `\fBx.nc\fP' از روی فایل CDL با نام `\fBfoo.cdl\fP':
.RS
.HP
ncgen3 \-o x.nc foo.cdl
.RE
.LP
تولید یک برنامه C شامل فراخوانی‌های توابع netCDF مورد نیاز برای ایجاد یک فایل netCDF دودویی معادل با نام `\fBx.nc\fP' از روی فایل CDL با نام `\fBfoo.cdl\fP':
.RS
.HP
ncgen3 \-c \-o x.nc foo.cdl
.RE
.LP.SH "نحوه استفاده (USAGE)"
.SS "خلاصه نحو CDL (CDL Syntax Summary)"
.LP
در زیر نمونه‌ای از نحو CDL آمده است که یک فایل netCDF را با چندین بُعد نام‌گذاری‌شده (lat، lon و time)، متغیرها (Z، t، p، rh، lat، lon، time)، مشخصه‌های متغیر (units، long_name، valid_range، _FillValue) و مقداری داده توصیف می‌کند. کلمات کلیدی CDL با حروف توپر (bold) مشخص شده‌اند. (این مثال صرفاً جهت نشان دادن نحو آورده شده است؛ یک فایل CDL واقعی مجموعه کامل‌تری از مشخصه‌ها را خواهد داشت تا داده‌ها به شکل خودتوصیف‌گر کامل‌تری ذخیره شوند.)

.RS
.nf
\fBnetcdf\fP foo {  // an example netCDF specification in CDL

\fBdimensions\fP:
	lat = 10, lon = 5, time = \fBunlimited\fP ;

\fBvariables\fP:
	\fBlong\fP    lat(lat), lon(lon), time(time);
	\fBfloat\fP   Z(time,lat,lon), t(time,lat,lon);
	\fBdouble\fP  p(time,lat,lon);
	\fBlong\fP    rh(time,lat,lon);

	// variable attributes
	lat:long_name = "latitude";
	lat:units = "degrees_north";
	lon:long_name = "longitude";
	lon:units = "degrees_east";
	time:units = "seconds since 1992-1-1 00:00:00";
	Z:units = "geopotential meters";
	Z:valid_range = 0., 5000.;
	p:_FillValue = \-9999.;
	rh:_FillValue = \-1;

\fBdata\fP:
	lat   = 0, 10, 20, 30, 40, 50, 60, 70, 80, 90;
	lon   = \-140, \-118, \-96, \-84, \-52;
}
.fi
.RE
.LP
تمامی دستورهای CDL با یک نقطه‌ویرگول ختم می‌شوند. از فاصله‌ها، تب‌ها و خطوط جدید می‌توان آزادانه برای خوانایی بیشتر استفاده کرد. توضیحات (کامنت‌ها) می‌توانند پس از نویسه‌های `//' در هر خطی قرار گیرند.
.LP
یک توصیف CDL از سه بخش اختیاری تشکیل شده است: \fIdimensions\fP،
\fIvariables\fP و \fIdata\fP، که به ترتیب با کلمات کلیدی
.BR dimensions: "،"
.BR variables:
و
.BR data
آغاز می‌شوند.
بخش متغیرها می‌تواند شامل \fIاعلان‌های متغیر (variable declarations)\fP
و \fIانتساب‌های مشخصه (attribute assignments)\fP باشد.
.LP
یک \fIdimension\fP در netCDF برای تعیین شکل یک یا چند متغیر چندبُعدی موجود در فایل netCDF استفاده می‌شود. یک بُعد netCDF دارای نام و اندازه است. حداکثر یک بُعد در فایل netCDF می‌تواند اندازه \fBunlimited\fP داشته باشد، به این معنی که متغیری که از این بُعد استفاده می‌کند می‌تواند به هر طولی افزایش یابد (مانند شماره رکورد در یک فایل).
.LP
یک \fIvariable\fP نمایانگر آرایه‌ای چندبُعدی از مقادیر هم‌نوع است. یک متغیر دارای یک نام، یک نوع داده و شکلی است که با فهرست ابعاد آن توصیف می‌شود. هر متغیر علاوه بر مقادیر داده، می‌تواند \fIمشخصه‌ها (attributes)\fP مرتبط نیز داشته باشد (به ادامه مراجعه کنید). نام، نوع داده و شکل یک متغیر توسط اعلان آن در بخش \fIvariable\fP از یک توصیف CDL تعیین می‌شود. یک متغیر ممکن است همنام با یک بُعد باشد؛ طبق قرارداد، چنین متغیری یک‌بُعدی است و مختصات بُعدی را که نام‌گذاری کرده است در بر دارد. ابعاد لزوماً نیازی به متغیرهای متناظر ندارند.
.LP
یک \fIattribute\fP در netCDF شامل اطلاعاتی درباره یک متغیر netCDF یا کل مجموعه‌داده netCDF است. مشخصه‌ها برای تعیین ویژگی‌هایی چون واحدها (units)، مقادیر خاص، حداکثر و حداقل مقادیر معتبر، ضریب‌های مقیاس‌بندی، آفست‌ها و پارامترها استفاده می‌شوند. اطلاعات مشخصه توسط مقادیر منفرد یا آرایه‌ای از مقادیر نشان داده می‌شوند. برای نمونه، "units" مشخصه‌ای است که با یک آرایه نویسه‌ای مانند "celsius" نمایش داده می‌شود. یک مشخصه دارای یک متغیر مرتبط، نام، نوع داده، طول و یک مقدار است. برخلاف متغیرها که برای داده‌ها در نظر گرفته شده‌اند، مشخصه‌ها برای فراداده (داده درباره داده‌ها) به کار می‌روند.
.LP
در CDL، یک مشخصه با نام متغیر و نام مشخصه که با `:' از هم جدا شده‌اند، مشخص می‌شود. می‌توان با استفاده از `:' پیش از نام مشخصه، مشخصه‌های \fIسراسری (global)\fP را که به متغیری وابسته نیستند به کل netCDF اختصاص داد. نوع داده یک مشخصه در CDL از نوع مقداری که به آن اختصاص داده شده است استخراج می‌شود. طول یک مشخصه برابر با تعداد مقادیر داده اختصاص‌یافته به آن، یا تعداد نویسه‌ها در رشته نویسه‌ای منتسب به آن است. مقادیر چندگانه برای مشخصه‌های غیرنویسه‌ای با جدا کردن مقادیر توسط کاما اختصاص می‌یابند. تمام مقادیر اختصاص داده شده به یک مشخصه باید از یک نوع باشند.
.LP
نام‌های ابعاد، متغیرها و مشخصه‌های CDL باید با یک نویسه الفبایی یا `_' شروع شوند و نویسه‌های بعدی می‌توانند حروف و ارقام یا `_' یا `\-' باشند.
.LP
بخش اختیاری \fIdata\fP در مشخصات CDL جایی است که متغیرهای netCDF می‌توانند مقداردهی اولیه شوند. نحو مقداردهی اولیه ساده است: نام متغیر، علامت مساوی و فهرستی از مقادیر ثابتِ جداشده با کاما (که می‌توانند با فاصله، تب و خط جدید از هم جدا شوند) که با یک نقطه‌ویرگول ختم می‌شود. برای آرایه‌های چندبُعدی، آخرین بُعد سریع‌ترین تغییر را دارد؛ بنابراین برای ماتریس‌ها به جای ترتیب ستونی از ترتیب سطری استفاده می‌شود. اگر مقادیر کمتری نسبت به آنچه برای پر کردن یک متغیر نیاز است ارائه شود، با یک `مقدار پرکننده' (fill value) وابسته به نوع گسترش می‌یابد، که این مقدار را می‌توان با ارائه مقداری برای یک مشخصه متغیر ویژه به نام `_FillValue' بازنویسی (override) کرد. نوع مقادیر ثابت نیازی به تطابق با نوع اعلان‌شده برای متغیر ندارد؛ برای مثال، تبدیل نوع خودکار (coercion) برای تبدیل اعداد صحیح به ممیز شناور انجام می‌شود. از مقدار ثابت `_' می‌توان برای تعیین مقدار پرکننده برای یک متغیر استفاده کرد..SS "انواع داده‌های اولیه (Primitive Data Types)"
.LP
.RS
.nf
\fBchar\fP	نویسه‌ها
\fBbyte\fP	داده‌های ۸ بیتی
\fBshort\fP	اعداد صحیح علامت‌دار ۱۶ بیتی
\fBlong\fP	اعداد صحیح علامت‌دار ۳۲ بیتی
\fBint\fP	(مترادف با \fBlong\fP)
\fBfloat\fP	ممیز شناور با دقت یگانه IEEE (۳۲ بیتی)
\fBreal\fP	(مترادف با \fBfloat\fP)
\fBdouble\fP	ممیز شناور با دقت مضاعف IEEE (۶۴ بیتی)
.fi
.RE
.LP
به‌جز نوع دادهٔ افزوده‌شدهٔ \fBbyte\fP و فقدان
\fBunsigned\fP،
زبان CDL از همان انواع داده‌های اولیهٔ C پشتیبانی می‌کند.
نام‌های انواع داده‌های اولیه از واژه‌های رزروشده در CDL هستند،
بنابراین نام متغیرها، ابعاد، و مشخصه‌ها نباید از
نام‌های انواع داده باشند. در اعلان‌ها، نام انواع داده را می‌توان
با حروف بزرگ یا کوچک مشخص کرد.
.LP
تفاوت بایت‌ها با نویسه‌ها در این است که آن‌ها برای نگه‌داری هشت بیت کامل
از داده در نظر گرفته شده‌اند، و بایت صفر هیچ اهمیت ویژه‌ای ندارد، بر خلاف
آنچه برای داده‌های نویسه‌ای وجود دارد.
برنامهٔ \fBncgen3\fP اعلان‌های \fBbyte\fP را در کد C خروجی به اعلان‌های \fBchar\fP
و در کد فرترن خروجی به اعلان غیراستاندارد \fBBYTE\fP
تبدیل می‌کند.
.LP
نوع‌های Short می‌توانند مقادیری بین \-32768 و 32767 را نگه‌داری کنند.
\fBncgen3\fP اعلان‌های \fBshort\fP را در کد C خروجی به اعلان‌های \fBshort\fP
و در کد فرترن خروجی به اعلان غیراستاندارد \fBINTEGER*2\fP
تبدیل می‌کند.
.LP
نوع‌های Long می‌توانند مقادیری بین \-2147483648 و 2147483647 را نگه‌داری کنند.
\fBncgen3\fP اعلان‌های \fBlong\fP را در کد C خروجی به اعلان‌های \fBlong\fP
و در کد فرترن خروجی به اعلان‌های \fBINTEGER\fP
تبدیل می‌کند. \fBint\fP و \fBinteger\fP به عنوان مترادف‌هایی برای \fBlong\fP
در اعلان‌های CDL پذیرفته می‌شوند.
اکنون که پلتفرم‌هایی با نمایش‌های ۶۴ بیتی برای نوع long در C وجود دارند، ممکن است
برای جلوگیری از سردرگمی، استفاده از مترادف \fBint\fP بهتر باشد.
.LP
نوع‌های Float می‌توانند مقادیری تقریباً بین \-3.4+38 و 3.4+38 را نگه‌داری کنند.
نمایش خارجی آن‌ها به صورت اعداد ممیز شناور ۳۲ بیتی استاندارد و نرمال‌شده با دقت یگانه IEEE است.
\fBncgen3\fP اعلان‌های \fBfloat\fP را در کد C خروجی به اعلان‌های \fBfloat\fP
و در کد فرترن خروجی به اعلان‌های \fBREAL\fP تبدیل می‌کند. \fBreal\fP
به عنوان مترادفی برای \fBfloat\fP در اعلان‌های CDL پذیرفته می‌شود.
.LP
نوع‌های Double می‌توانند مقادیری تقریباً بین \-1.7+308 و 1.7+308 را نگه‌داری کنند.
نمایش خارجی آن‌ها به صورت اعداد ممیز شناور ۶۴ بیتی استاندارد نرمال‌شده با دقت مضاعف IEEE است.
\fBncgen3\fP اعلان‌های \fBdouble\fP را در کد C خروجی به اعلان‌های \fBdouble\fP
و در کد فرترن خروجی به اعلان‌های \fBDOUBLE PRECISION\fP
تبدیل می‌کند.
.LP
.SS "ثابت‌های CDL (CDL Constants)"
.LP
ثابت‌های تخصیص‌یافته به مشخصه‌ها یا متغیرها می‌توانند از هر یک از
انواع پایه‌ای netCDF باشند. نحو نوشتن ثابت‌ها مشابه نحو زبان C است،
به‌جز اینکه برای متمایز کردن مقادیر short و float از longs و doubles
باید پسوندهای نوع به آن‌ها ضمیمه شوند.
.LP
یک ثابت \fIbyte\fP توسط یک نویسه تکی یا یک دنباله گریز (escape sequence)
چندنویسه‌ای محصور در کوتیشن تکی نمایش داده می‌شود. برای مثال،
.RS
.nf
 'a'		// نویسه `a` در ASCII
 '\\0'		// یک بایت صفر
 '\\n'		// نویسه خط جدید در ASCII
 '\\33'		// نویسه گریز ASCII (هشت‌هشتی ۳۳)
 '\\x2b'	// مثبت در ASCII (شانزده‌شانزدهی 2b)
 '\\377'	// ۳۷۷ هشت‌هشتی = ۲۵۵ ده‌دهی، غیر ASCII
.fi
.RE
.LP
ثابت‌های نویسه‌ای درون دابل کوتیشن محصور می‌شوند. یک آرایهٔ نویسه‌ای
می‌تواند به صورت یک رشته محصور در دابل کوتیشن نمایش داده شود. قواعد معمول
گریز رشته در زبان C معتبر هستند. برای مثال
.RS
.nf
"a"		// نویسه `a` در ASCII
"Two\\nlines\\n"	// یک رشته ۱۰ نویسه‌ای با دو خط جدید تعبیه‌شده
"a bell:\\007"	// رشته‌ای حاوی زنگ ASCII
.fi
.RE
توجه داشته باشید که آرایهٔ نویسه‌ای netCDF با مقدار "a" در یک متغیر
تک‌عنصری جای می‌گیرد، چرا که هیچ نویسهٔ پایانی NULL در نظر گرفته نمی‌شود. با این حال، یک بایت
صفر در آرایهٔ نویسه‌ای، با پیروی از قرارداد C، توسط برنامهٔ \fBncdump\fP به عنوان پایان نویسه‌های
بااهمیت تفسیر می‌شود. بنابراین، نباید یک بایت NULL در یک رشتهٔ نویسه‌ای جاسازی شود مگر
در انتهای آن: برای آرایه‌های بایتی که حاوی بایت صفر هستند، به‌جای آن از نوع دادهٔ \fIbyte\fP
استفاده کنید. NetCDF و CDL هیچ نوع داده‌ای برای رشته ندارند، بلکه فقط
آرایه‌های نویسه‌ای با طول ثابت دارند که ممکن است چندبعدی باشند.
.LP
ثابت‌های عدد صحیح \fIshort\fP برای نمایش مقادیر ۱۶ بیتی
علامت‌دار در نظر گرفته شده‌اند. شکل یک ثابت \fIshort\fP به صورت یک ثابت
عدد صحیح است که یک `s' یا `S' به آن ضمیمه شده است. اگر یک ثابت \fIshort\fP
با `0' شروع شود، به عنوان هشت‌هشتی تفسیر می‌شود، به جز زمانی که با
`0x' آغاز شود که در این صورت به عنوان یک ثابت شانزده‌شانزدهی تفسیر می‌گردد. برای مثال:
.RS
.nf
\-2s	// مقدار \-2 از نوع short
0123s	// هشت‌هشتی (octal)
0x7ffs  //شانزده‌شانزدهی (hexadecimal)
.fi
.RE
.LP
ثابت‌های عدد صحیح \fILong\fP برای نمایش مقادیر ۳۲ بیتی علامت‌دار
در نظر گرفته شده‌اند. شکل یک ثابت \fIlong\fP به صورت یک ثابت عدد صحیح معمولی
است، اگرچه ضمیمه کردن یک `l' یا `L' اختیاری نیز قابل قبول است.
اگر یک ثابت \fIlong\fP با `0' شروع شود، به عنوان هشت‌هشتی تفسیر می‌شود،
به جز حالتی که با `0x' شروع شود که به عنوان یک ثابت شانزده‌شانزدهی
تفسیر می‌گردد. مثال‌هایی از ثابت‌های معتبر \fIlong\fP عبارتند از:
.RS
.nf
\-2
1234567890L
0123		// هشت‌هشتی (octal)
0x7ff		// شانزده‌شانزدهی (hexadecimal)
.fi
.RE
.LP
ثابت‌های ممیز شناور از نوع \fIfloat\fP برای نمایش داده‌های
ممیز شناور با حدود هفت رقم بااهمیت دقت مناسب هستند.
شکل یک ثابت \fIfloat\fP مشابه یک ثابت ممیز شناور زبان C است
که یک `f' یا `F' به انتهای آن افزوده شده است. برای مثال موارد زیر
همگی ثابت‌های قابل قبول \fIfloat\fP هستند:
.RS
.nf
\-2.0f
3.14159265358979f	// به دقت کمتری کوتاه خواهد شد
1.f

.fi
.RE
.LP
ثابت‌های ممیز شناور از نوع \fIdouble\fP برای
نمایش داده‌های ممیز شناور با حدود شانزده رقم بااهمیت
دقت مناسب هستند. شکل یک ثابت \fIdouble\fP همانند یک ثابت
ممیز شناور در C است. یک `d' یا `D' اختیاری می‌تواند به آن ضمیمه شود.
برای مثال موارد زیر همگی ثابت‌های قابل قبول \fIdouble\fP هستند:
.RS
.nf
\-2.0
3.141592653589793
1.0e-20
1.d
.fi
.RE.SH "گزارش باگ‌ها (BUGS)"
.LP
برنامه‌های تولیدشده توسط \fBncgen3\fP هنگام استفاده از \fB-c\fP یا \fB-f\fP، از دستورهای مقداردهی اولیه برای ذخیره داده‌ها در متغیرها استفاده می‌کنند و در صورت تلاش برای استفاده از آن‌ها برای مجموعه‌داده‌های بزرگ، در تولید برنامه‌های قابل کامپایل ناموفق خواهند بود؛ زیرا ممکن است دستورهای حاصل از طول خط یا تعداد دستورهای ادامه‌دار (continuation statements) مجاز توسط کامپایلر فراتر بروند.
.LP
نحو CDL انتساب آنچه را که شبیه به آرایه‌ای از رشته‌های با طول متغیر به نظر می‌رسد به یک متغیر netCDF آسان می‌کند، اما این رشته‌ها صرفاً در قالب یک آرایه واحد از نویسه‌ها به یکدیگر الحاق خواهند شد، چرا که netCDF نمی‌تواند آرایه‌ای از رشته‌های با طول متغیر را در یک متغیر netCDF نمایش دهد.
.LP
‏NetCDF و CDL هنوز از نوع داده‌ای متناظر با عدد صحیح ۶۴ بیتی پشتیبانی نمی‌کنند.