.\" $Header$ .nr yr \n(yr+1900 .af mo 01 .af dy 01 .TH ncmpigen 1 "PnetCDF 1.14.1" "Printed: \n(yr-\n(mo-\n(dy" "PnetCDF utilities" .SH "نام (NAME)" ncmpigen \- تولید یک فایل netCDF، یک برنامه C، یا یک برنامه Fortran از روی یک فایل CDL .SH "خلاصه دستور (SYNOPSIS)" .HP ncmpigen .nh \%[-b] \%[-c] \%[-f] \%[-n] \%[-o \fInetcdf_filename\fP] \%[-v \fIfile_format\fP] \%\fIinput_file\fP .hy .ft .SH "توضیحات (DESCRIPTION)" دستور \fBncmpigen\fP یک فایل netCDF یا کد منبع زبان‌های C یا Fortran را جهت ایجاد یک فایل netCDF تولید می‌کند. ورودی \fBncmpigen\fP توصیفی از یک فایل netCDF به زبان کوچکی موسوم به CDL (سرنام network Common Data form Language) است که در ادامه شرح داده شده است. اگر هیچ گزینه‌ای هنگام اجرای \fBncmpigen\fP مشخص نشود، این دستور صرفاً نحو (syntax) فایل CDL ورودی را بررسی کرده و در صورت وجود هرگونه نقض قواعد نحو CDL، پیام خطا صادر می‌کند. از گزینه‌های دیگر می‌توان برای ایجاد فایل netCDF متناظر، تولید یک برنامه C که با استفاده از واسط C مربوط به netCDF فایل netCDF را ایجاد می‌کند، یا تولید یک برنامه Fortran که با استفاده از واسط Fortran مربوط به netCDF همان فایل netCDF را می‌سازد، استفاده کرد. .LP برنامه \fBncmpigen\fP می‌تواند به همراه ابزار مکمل خود \fBncmpidump\fP برای انجام برخی عملیات ساده روی فایل‌های netCDF استفاده شود. به عنوان مثال، جهت تغییر نام یک بُعد در یک فایل netCDF، از \fBncmpidump\fP برای دریافت نسخه CDL از فایل netCDF استفاده کنید، سپس فایل CDL را برای تغییر نام ابعاد ویرایش کرده، و در نهایت از \fBncmpigen\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 را نمی‌توان مستقیماً در خروجی استاندارد نوشت، زیرا خروجی استاندارد قابلیت جستجو و جابجایی (seekable) ندارد.) .IP "\fB-n\fP" مشابه گزینه \fB-b\fP است، با این تفاوت که در صورت عدم تعیین نام فایل خروجی توسط گزینه \fB-o\fP، فایل netCDF را به جای پسوند «‎.nc» با پسوند منسوخ‌شده «‎.cdf» ایجاد می‌کند. این گزینه صرفاً برای حفظ سازگاری با گذشته پشتیبانی می‌شود. .IP "\fB-v\fP \fRfile_format\fP" قالب فایل netCDF خروجی. مقدار \fRfile_format\fP می‌تواند یکی از موارد زیر باشد: 1 یا classic برای قالب CDF-1. 2 یا 64-bit-offset برای CDF-2. 5 یا 64-bit-variable برای CDF-5. حالت پیش‌فرض (در صورت تعیین نشدن این گزینه) CDF-1 یا همان قالب classic است. .SH "مثال‌ها (EXAMPLES)" .LP بررسی نحو فایل CDL با نام «\fBfoo.cdl\fP»: .RS .HP ncmpigen foo.cdl .RE .LP تولید یک فایل netCDF دودویی معادل به نام «\fBx.nc\fP» از روی فایل CDL به نام «\fBfoo.cdl\fP»: .RS .HP ncmpigen -o x.nc foo.cdl .RE .LP تولید یک برنامه C شامل فراخوانی‌های توابع netCDF مورد نیاز برای ایجاد یک فایل netCDF دودویی معادل به نام «\fBx.nc\fP» از روی فایل CDL به نام «\fBfoo.cdl\fP»: .RS .HP ncmpigen -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 به صورت پررنگ مشخص شده‌اند. (این مثال برای نشان دادن نحو آورده شده است؛ یک فایل 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 با یک نقطه\-ویرگول خاتمه می‌یابند. فاصله‌ها، تب‌ها و خطوط جدید می‌توانند آزادانه برای خوانایی بهتر استفاده شوند. توضیحات می‌توانند پس از نویسه‌های \(lq//\(rq در هر خطی قرار گیرند. .LP یک توصیف CDL از سه بخش اختیاری تشکیل شده است: \fIابعاد (dimensions)\fP، \fIمتغیرها (variables)\fP و \fIداده‌ها (data)\fP، که به‌ترتیب با کلیدواژه‌های .BR dimensions: ، .BR variables: و .BR data آغاز می‌شوند. بخش متغیرها می‌تواند شامل \fIاعلان‌های متغیر\fP و \fIانتساب‌های ویژگی\fP باشد. .LP یک \fIبُعد\fP در netCDF برای تعیین شکل یک یا چند متغیر چندبُعدی موجود در فایل netCDF به کار می‌رود. یک بُعد netCDF دارای یک نام و یک اندازه است. در یک فایل netCDF حداکثر یک بُعد می‌تواند اندازه \fBunlimited\fP داشته باشد، به این معنی که متغیری که از این بُعد استفاده می‌کند می‌تواند به هر طولی رشد کند (مانند شماره رکورد در یک فایل). .LP یک \fIمتغیر\fP نمایانگر یک آرایه چندبُعدی از مقادیر هم‌نوع است. یک متغیر دارای یک نام، یک نوع داده و یک شکل است که توسط فهرست ابعاد آن توصیف می‌شود. هر متغیر می‌تواند علاوه بر مقادیر داده، \fIویژگی‌ها\fP (در ادامه را ببینید) نیز داشته باشد. نام، نوع داده و شکل یک متغیر با اعلان آن در بخش \fIvariables\fP از یک توصیف CDL مشخص می‌شود. یک متغیر می‌تواند نامی مشابه با یک بُعد داشته باشد؛ طبق قرارداد، چنین متغیری یک‌بُعدی است و مختصات بُعد هم‌نام خود را در بر دارد. ابعاد لزوماً نیازی به داشتن متغیرهای متناظر ندارند. .LP یک \fIویژگی\fP در netCDF حاوی اطلاعاتی درباره یک متغیر netCDF یا کل مجموعه داده‌های netCDF است. ویژگی‌ها برای تعیین مشخصاتی نظیر واحدها، مقادیر ویژه، مقادیر معتبر بیشینه و کمینه، ضرایب مقیاس‌بندی، آفست‌ها و پارامترها به کار می‌روند. اطلاعات ویژگی توسط مقادیر منفرد یا آرایه‌ای از مقادیر نشان داده می‌شوند. برای نمونه، \(lqunits\(rq ویژگی‌ای است که با یک آرایه نویسه‌ای مانند \(lqcelsius\(rq نشان داده می‌شود. یک ویژگی دارای یک متغیر مرتبط، یک نام، یک نوع داده، یک طول و یک مقدار است. برخلاف متغیرها که برای داده‌ها در نظر گرفته شده‌اند، ویژگی‌ها برای فراداده (داده درباره داده) هستند. .LP در CDL، یک ویژگی با یک نام متغیر و یک نام ویژگی که با \(lq:\(rq از هم جدا شده‌اند، مشخص می‌شود. می‌توان ویژگی‌های \fIسراسری (global)\fP را که به هیچ متغیری وابسته نیستند، با قرار دادن \(lq:\(rq قبل از نام ویژگی، به کل netCDF اختصاص داد. نوع داده یک ویژگی در CDL از نوع مقداری که به آن اختصاص داده شده است مشتق می‌شود. طول یک ویژگی برابر است با تعداد مقادیر داده اختصاص‌یافته به آن، یا تعداد نویسه‌های رشته نویسه‌ایِ اختصاص‌یافته به آن. برای اختصاص چندین مقدار به ویژگی‌های غیرنویسه‌ای، مقادیر با ویرگول از یکدیگر جدا می‌شوند. همه مقادیر اختصاص‌یافته به یک ویژگی باید از یک نوع باشند. .LP نام‌های ابعاد، متغیرها و ویژگی‌های CDL باید با یک نویسه الفبایی یا \(lq_\(rq آغاز شوند و نویسه‌های بعدی می‌توانند حروف یا ارقام یا \(lq_\(rq یا \(lq\-\(rq باشند. .LP بخش اختیاری \fIdata\fP در یک مشخصات CDL جایی است که متغیرهای netCDF می‌توانند مقداردهی اولیه شوند. نحو مقداردهی اولیه ساده است: نام یک متغیر، یک علامت مساوی و فهرستی از ثابت‌های جداشده با ویرگول (که احتمالاً با فاصله، تب و خطوط جدید از هم جدا شده‌اند) که با یک نقطه\-ویرگول ختم می‌شود. برای آرایه‌های چندبُعدی، آخرین بُعد سریع‌ترین تغییر را دارد. بنابراین برای ماتریس‌ها ترتیب سطری (row-order) به جای ترتیب ستونی (column-order) استفاده می‌شود. اگر مقادیر کمتری نسبت به مقدار مورد نیاز برای پر کردن یک متغیر ارائه شود، با یک \(lqمقدار پرکننده\(rq (fill value) وابسته به نوع گسترش می‌یابد، که می‌تواند با ارائه مقداری برای یک ویژگی متمایز متغیر به نام \(lq_FillValue\(rq بازنویسی شود. نوع ثابت‌ها نیازی نیست با نوع اعلان‌شده برای متغیر مطابقت داشته باشد؛ تبدیل‌های نوع (coercions) به عنوان مثال برای تبدیل اعداد صحیح به ممیز شناور انجام می‌شوند. ثابت \(lq_\(rq می‌تواند برای تعیین مقدار پرکننده برای یک متغیر استفاده شود..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 بایت‌ها از این جهت با نویسه‌ها تفاوت دارند که برای نگهداری هشت بیت کامل از داده‌ها در نظر گرفته شده‌اند، و بایت صفر هیچ اهمیت خاصی ندارد، برخلاف داده‌های نویسه‌ای که بایت صفر در آن‌ها پایان رشته را نشان می‌دهد. دستور \fBncmpigen\fP اعلان‌های \fBbyte\fP را در کد C خروجی به اعلان‌های \fBchar\fP و در کد Fortran خروجی به اعلان غیراستاندارد \fBBYTE\fP تبدیل می‌کند. .LP نوع Short می‌تواند مقادیری بین \-32768 و 32767 را در خود نگه دارد. دستور \fBncmpigen\fP اعلان‌های \fBshort\fP را در کد C خروجی به اعلان‌های \fBshort\fP و در کد Fortran خروجی به اعلان غیراستاندارد \fBINTEGER*2\fP تبدیل می‌کند. .LP نوع Long می‌تواند مقادیری بین \-2147483648 و 2147483647 را در خود نگه دارد. دستور \fBncmpigen\fP اعلان‌های \fBlong\fP را در کد C خروجی به اعلان‌های \fBlong\fP و در کد Fortran خروجی به اعلان‌های \fBINTEGER\fP تبدیل می‌کند. در اعلان‌های CDL، عبارت‌های \fBint\fP و \fBinteger\fP به عنوان مترادف‌هایی برای \fBlong\fP پذیرفته می‌شوند. اکنون که پلتفرم‌هایی با نمایش ۶۴ بیتی برای نوع long زبان C وجود دارند، بهتر است برای جلوگیری از سردرگمی از مترادف \fBint\fP استفاده شود. .LP نوع Float می‌تواند مقادیری بین حدود \-3.4+38 و 3.4+38 را در خود نگه دارد. نمایش خارجی آن‌ها به صورت اعداد ممیز شناور ۳۲ بیتی دقت یگانهٔ نرمال‌شدهٔ استاندارد IEEE است. دستور \fBncmpigen\fP اعلان‌های \fBfloat\fP را در کد C خروجی به اعلان‌های \fBfloat\fP و در کد Fortran خروجی به اعلان‌های \fBREAL\fP تبدیل می‌کند. در اعلان‌های CDL، عبارت \fBreal\fP به عنوان مترادفی برای \fBfloat\fP پذیرفته می‌شود. .LP نوع Double می‌تواند مقادیری بین حدود \-1.7+308 و 1.7+308 را در خود نگه دارد. نمایش خارجی آن‌ها به صورت اعداد ممیز شناور ۶۴ بیتی دقت مضاعف استاندارد و نرمال‌شدهٔ IEEE است. دستور \fBncmpigen\fP اعلان‌های \fBdouble\fP را در کد C خروجی به اعلان‌های \fBdouble\fP و در کد Fortran خروجی به اعلان‌های \fBDOUBLE PRECISION\fP تبدیل می‌کند. .LP .SS "ثابت‌های CDL (CDL Constants)" .LP ثابت‌های اختصاص‌یافته به مشخصه‌ها یا متغیرها می‌توانند از هر یک از انواع پایه‌ای netCDF باشند. نحو (syntax) ثابت‌ها مشابه نحو C است، با این تفاوت که باید پسوندهای نوع به shortها و floatها اضافه شوند تا از longها و doubleها متمایز گردند. .LP یک ثابت \fIbyte\fP با یک تک‌نویسه یا یک دنبالهٔ گریز چندنویسه‌ای که درون نقل‌قول‌های تکی محصور شده است، نمایش داده می‌شود. برای مثال: .RS .nf 'a' // ASCII `a' '\\0' // a zero byte '\\n' // ASCII newline character '\\33' // ASCII escape character (33 octal) '\\x2b' // ASCII plus (2b hex) '\\377' // 377 octal = 255 decimal, non-ASCII .fi .RE .LP ثابت‌های نویسه‌ای درون نقل‌قول‌های دوتایی قرار می‌گیرند. یک آرایهٔ نویسه‌ای می‌تواند به عنوان یک رشتهٔ محصور در نقل‌قول‌های دوتایی نمایش داده شود. قواعد متداول گریز رشته در C رعایت می‌شوند. برای مثال: .RS .nf "a" // ASCII `a' "Two\\nlines\\n" // a 10-character string with two embedded newlines "a bell:\\007" // a string containing an ASCII bell .fi .RE توجه داشته باشید که آرایهٔ نویسه‌ای netCDF با مقدار "a" در یک متغیر تک‌عنصری جای می‌گیرد، چرا که هیچ نویسهٔ NULL پایانی برای آن در نظر گرفته نمی‌شود. با این حال، طبق قراردادهای زبان C، یک بایت صفر در یک آرایهٔ نویسه‌ای توسط برنامهٔ \fBncmpidump\fP به عنوان پایان نویسه‌های معنادار تفسیر می‌شود. بنابراین، یک بایت NULL نباید درون یک رشتهٔ نویسه‌ای قرار داده شود مگر اینکه در انتهای آن باشد: برای آرایه‌های بایتی حاوی بایت صفر، در عوض از نوع دادهٔ \fIbyte\fP استفاده کنید. NetCDF و CDL هیچ نوع رشته‌ای (string) ندارند، بلکه فقط آرایه‌های نویسه‌ای با طول ثابت دارند که می‌توانند چندبعدی باشند. .LP ثابت‌های صحیح \fIshort\fP برای نمایش مقادیر ۱۶ بیتی علامت‌دار در نظر گرفته شده‌اند. شکل یک ثابت \fIshort\fP یک ثابت عدد صحیح است که یک \(aqs\(aq یا \(aqS\(aq به انتهای آن افزوده شده است. اگر یک ثابت \fIshort\fP با \(aq0\(aq آغاز شود، به صورت مبنای هشت (octal) تفسیر می‌شود، مگر اینکه با \(aq0x\(aq آغاز شود که در این صورت به عنوان یک ثابت در مبنای شانزده (hexadecimal) تفسیر خواهد شد. برای مثال: .RS .nf \-2s // a short -2 0123s // octal 0x7ffs //hexadecimal .fi .RE .LP ثابت‌های صحیح \fILong\fP برای نمایش مقادیر ۳۲ بیتی علامت‌دار در نظر گرفته شده‌اند. شکل یک ثابت \fIlong\fP مانند یک ثابت عدد صحیح معمولی است، هرچند افزودن یک \(aql\(aq یا \(aqL\(aq اختیاری نیز به انتهای آن مجاز است. اگر یک ثابت \fIlong\fP با \(aq0\(aq آغاز شود، به صورت مبنای هشت تفسیر می‌شود، مگر اینکه با \(aq0x\(aq آغاز گردد که در این صورت به عنوان یک ثابت مبنای شانزده تفسیر می‌شود. مثال‌هایی از ثابت‌های معتبر \fIlong\fP عبارتند از: .RS .nf \-2 1234567890L 0123i // octal 0x7ff // hexadecimal .fi .RE .LP ثابت‌های ممیز شناور از نوع \fIfloat\fP برای نمایش داده‌های ممیز شناور با دقتی در حدود هفت رقم بااهمیت مناسب هستند. شکل یک ثابت \fIfloat\fP مانند یک ثابت ممیز شناور C است که یک \(aqf\(aq یا \(aqF\(aq به انتهای آن اضافه شده باشد. برای مثال موارد زیر همگی ثابت‌های \fIfloat\fP معتبر و قابل قبول هستند: .RS .nf \-2.0f 3.14159265358979f // will be truncated to less precision 1.f .1f .fi .RE .LP ثابت‌های ممیز شناور از نوع \fIdouble\fP برای نمایش داده‌های ممیز شناور با دقتی در حدود شانزده رقم بااهمیت مناسب هستند. شکل یک ثابت \fIdouble\fP همانند یک ثابت ممیز شناور C است. یک \(aqd\(aq یا \(aqD\(aq اختیاری را می‌توان به انتهای آن افزود. برای مثال موارد زیر همگی ثابت‌های \fIdouble\fP قابل قبول هستند: .RS .nf \-2.0 3.141592653589793 1.0e-20 1.d .fi .RE.SH "تاریخ (DATE)" ۳۱ ژوئیه ۲۰۲۵ .SH "گزارش باگ‌ها (BUGS)" .LP برنامه‌های تولیدشده توسط \fBncmpigen\fP هنگام استفاده از \fB-c\fP یا \fB-f\fP، از دستورهای مقداردهی اولیه برای ذخیرهٔ داده‌ها در متغیرها استفاده می‌کنند و در صورتی که تلاش کنید از آن‌ها برای مجموعه‌داده‌های بزرگ استفاده نمایید، در تولید برنامه‌های قابل کامپایل ناموفق خواهند بود؛ زیرا دستورهای حاصل ممکن است از طول خط یا تعداد خطوط ادامه‌دار مجاز توسط کامپایلر فراتر بروند. .LP نحو CDL انتساب ساختاری شبیه به یک آرایه از رشته‌های با طول متغیر به یک متغیر netCDF را آسان می‌سازد، اما این رشته‌ها صرفاً در یک آرایهٔ واحد از کاراکترها به یکدیگر متصل خواهند شد، چرا که netCDF نمی‌تواند آرایه‌ای از رشته‌های با طول متغیر را درون یک متغیر netCDF نمایش دهد. .LP ‏NetCDF و CDL هنوز از نوعی متناظر با یک عدد صحیح ۶۴ بیتی پشتیبانی نمی‌کنند.