خلاصه نحو CDL (CDL Syntax Summary)

در زیر نمونه‌ای از نحو CDL آمده است که یک فایل netCDF را با چندین بُعد نام‌گذاری‌شده (lat، lon و time)، متغیرها (Z، t، p، rh، lat، lon، time)، مشخصه‌های متغیر (units، long_name، valid_range، _FillValue) و مقداری داده توصیف می‌کند. کلمات کلیدی CDL با حروف توپر (bold) مشخص شده‌اند. (این مثال صرفاً جهت نشان دادن نحو آورده شده است؛ یک فایل CDL واقعی مجموعه کامل‌تری از مشخصه‌ها را خواهد داشت تا داده‌ها به شکل خودتوصیف‌گر کامل‌تری ذخیره شوند.)

netcdf foo {  // an example netCDF specification in CDL
dimensions:
	lat = 10, lon = 5, time = unlimited ;
variables:
	long    lat(lat), lon(lon), time(time);
	float   Z(time,lat,lon), t(time,lat,lon);
	double  p(time,lat,lon);
	long    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;
data:
	lat   = 0, 10, 20, 30, 40, 50, 60, 70, 80, 90;
	lon   = -140, -118, -96, -84, -52;
}

تمامی دستورهای CDL با یک نقطه‌ویرگول ختم می‌شوند. از فاصله‌ها، تب‌ها و خطوط جدید می‌توان آزادانه برای خوانایی بیشتر استفاده کرد. توضیحات (کامنت‌ها) می‌توانند پس از نویسه‌های `//' در هر خطی قرار گیرند.

یک توصیف CDL از سه بخش اختیاری تشکیل شده است: dimensions، variables و data، که به ترتیب با کلمات کلیدی dimensions:، variables: و data آغاز می‌شوند. بخش متغیرها می‌تواند شامل اعلان‌های متغیر (variable declarations) و انتساب‌های مشخصه (attribute assignments) باشد.

یک dimension در netCDF برای تعیین شکل یک یا چند متغیر چندبُعدی موجود در فایل netCDF استفاده می‌شود. یک بُعد netCDF دارای نام و اندازه است. حداکثر یک بُعد در فایل netCDF می‌تواند اندازه unlimited داشته باشد، به این معنی که متغیری که از این بُعد استفاده می‌کند می‌تواند به هر طولی افزایش یابد (مانند شماره رکورد در یک فایل).

یک variable نمایانگر آرایه‌ای چندبُعدی از مقادیر هم‌نوع است. یک متغیر دارای یک نام، یک نوع داده و شکلی است که با فهرست ابعاد آن توصیف می‌شود. هر متغیر علاوه بر مقادیر داده، می‌تواند مشخصه‌ها (attributes) مرتبط نیز داشته باشد (به ادامه مراجعه کنید). نام، نوع داده و شکل یک متغیر توسط اعلان آن در بخش variable از یک توصیف CDL تعیین می‌شود. یک متغیر ممکن است همنام با یک بُعد باشد؛ طبق قرارداد، چنین متغیری یک‌بُعدی است و مختصات بُعدی را که نام‌گذاری کرده است در بر دارد. ابعاد لزوماً نیازی به متغیرهای متناظر ندارند.

یک attribute در netCDF شامل اطلاعاتی درباره یک متغیر netCDF یا کل مجموعه‌داده netCDF است. مشخصه‌ها برای تعیین ویژگی‌هایی چون واحدها (units)، مقادیر خاص، حداکثر و حداقل مقادیر معتبر، ضریب‌های مقیاس‌بندی، آفست‌ها و پارامترها استفاده می‌شوند. اطلاعات مشخصه توسط مقادیر منفرد یا آرایه‌ای از مقادیر نشان داده می‌شوند. برای نمونه، "units" مشخصه‌ای است که با یک آرایه نویسه‌ای مانند "celsius" نمایش داده می‌شود. یک مشخصه دارای یک متغیر مرتبط، نام، نوع داده، طول و یک مقدار است. برخلاف متغیرها که برای داده‌ها در نظر گرفته شده‌اند، مشخصه‌ها برای فراداده (داده درباره داده‌ها) به کار می‌روند.

در CDL، یک مشخصه با نام متغیر و نام مشخصه که با `:' از هم جدا شده‌اند، مشخص می‌شود. می‌توان با استفاده از `:' پیش از نام مشخصه، مشخصه‌های سراسری (global) را که به متغیری وابسته نیستند به کل netCDF اختصاص داد. نوع داده یک مشخصه در CDL از نوع مقداری که به آن اختصاص داده شده است استخراج می‌شود. طول یک مشخصه برابر با تعداد مقادیر داده اختصاص‌یافته به آن، یا تعداد نویسه‌ها در رشته نویسه‌ای منتسب به آن است. مقادیر چندگانه برای مشخصه‌های غیرنویسه‌ای با جدا کردن مقادیر توسط کاما اختصاص می‌یابند. تمام مقادیر اختصاص داده شده به یک مشخصه باید از یک نوع باشند.

نام‌های ابعاد، متغیرها و مشخصه‌های CDL باید با یک نویسه الفبایی یا `_' شروع شوند و نویسه‌های بعدی می‌توانند حروف و ارقام یا `_' یا `-' باشند.

بخش اختیاری data در مشخصات CDL جایی است که متغیرهای netCDF می‌توانند مقداردهی اولیه شوند. نحو مقداردهی اولیه ساده است: نام متغیر، علامت مساوی و فهرستی از مقادیر ثابتِ جداشده با کاما (که می‌توانند با فاصله، تب و خط جدید از هم جدا شوند) که با یک نقطه‌ویرگول ختم می‌شود. برای آرایه‌های چندبُعدی، آخرین بُعد سریع‌ترین تغییر را دارد؛ بنابراین برای ماتریس‌ها به جای ترتیب ستونی از ترتیب سطری استفاده می‌شود. اگر مقادیر کمتری نسبت به آنچه برای پر کردن یک متغیر نیاز است ارائه شود، با یک `مقدار پرکننده' (fill value) وابسته به نوع گسترش می‌یابد، که این مقدار را می‌توان با ارائه مقداری برای یک مشخصه متغیر ویژه به نام `_FillValue' بازنویسی (override) کرد. نوع مقادیر ثابت نیازی به تطابق با نوع اعلان‌شده برای متغیر ندارد؛ برای مثال، تبدیل نوع خودکار (coercion) برای تبدیل اعداد صحیح به ممیز شناور انجام می‌شود. از مقدار ثابت `_' می‌توان برای تعیین مقدار پرکننده برای یک متغیر استفاده کرد..SS "انواع داده‌های اولیه (Primitive Data Types)"

char	نویسه‌ها
byte	داده‌های ۸ بیتی
short	اعداد صحیح علامت‌دار ۱۶ بیتی
long	اعداد صحیح علامت‌دار ۳۲ بیتی
int	(مترادف با long)
float	ممیز شناور با دقت یگانه IEEE (۳۲ بیتی)
real	(مترادف با float)
double	ممیز شناور با دقت مضاعف IEEE (۶۴ بیتی)

به‌جز نوع دادهٔ افزوده‌شدهٔ byte و فقدان unsigned، زبان CDL از همان انواع داده‌های اولیهٔ C پشتیبانی می‌کند. نام‌های انواع داده‌های اولیه از واژه‌های رزروشده در CDL هستند، بنابراین نام متغیرها، ابعاد، و مشخصه‌ها نباید از نام‌های انواع داده باشند. در اعلان‌ها، نام انواع داده را می‌توان با حروف بزرگ یا کوچک مشخص کرد.

تفاوت بایت‌ها با نویسه‌ها در این است که آن‌ها برای نگه‌داری هشت بیت کامل از داده در نظر گرفته شده‌اند، و بایت صفر هیچ اهمیت ویژه‌ای ندارد، بر خلاف آنچه برای داده‌های نویسه‌ای وجود دارد. برنامهٔ ncgen3 اعلان‌های byte را در کد C خروجی به اعلان‌های char و در کد فرترن خروجی به اعلان غیراستاندارد BYTE تبدیل می‌کند.

نوع‌های Short می‌توانند مقادیری بین -32768 و 32767 را نگه‌داری کنند. ncgen3 اعلان‌های short را در کد C خروجی به اعلان‌های short و در کد فرترن خروجی به اعلان غیراستاندارد INTEGER*2 تبدیل می‌کند.

نوع‌های Long می‌توانند مقادیری بین -2147483648 و 2147483647 را نگه‌داری کنند. ncgen3 اعلان‌های long را در کد C خروجی به اعلان‌های long و در کد فرترن خروجی به اعلان‌های INTEGER تبدیل می‌کند. int و integer به عنوان مترادف‌هایی برای long در اعلان‌های CDL پذیرفته می‌شوند. اکنون که پلتفرم‌هایی با نمایش‌های ۶۴ بیتی برای نوع long در C وجود دارند، ممکن است برای جلوگیری از سردرگمی، استفاده از مترادف int بهتر باشد.

نوع‌های Float می‌توانند مقادیری تقریباً بین -3.4+38 و 3.4+38 را نگه‌داری کنند. نمایش خارجی آن‌ها به صورت اعداد ممیز شناور ۳۲ بیتی استاندارد و نرمال‌شده با دقت یگانه IEEE است. ncgen3 اعلان‌های float را در کد C خروجی به اعلان‌های float و در کد فرترن خروجی به اعلان‌های REAL تبدیل می‌کند. real به عنوان مترادفی برای float در اعلان‌های CDL پذیرفته می‌شود.

نوع‌های Double می‌توانند مقادیری تقریباً بین -1.7+308 و 1.7+308 را نگه‌داری کنند. نمایش خارجی آن‌ها به صورت اعداد ممیز شناور ۶۴ بیتی استاندارد نرمال‌شده با دقت مضاعف IEEE است. ncgen3 اعلان‌های double را در کد C خروجی به اعلان‌های double و در کد فرترن خروجی به اعلان‌های DOUBLE PRECISION تبدیل می‌کند.

ثابت‌های CDL (CDL Constants)

ثابت‌های تخصیص‌یافته به مشخصه‌ها یا متغیرها می‌توانند از هر یک از انواع پایه‌ای netCDF باشند. نحو نوشتن ثابت‌ها مشابه نحو زبان C است، به‌جز اینکه برای متمایز کردن مقادیر short و float از longs و doubles باید پسوندهای نوع به آن‌ها ضمیمه شوند.

یک ثابت byte توسط یک نویسه تکی یا یک دنباله گریز (escape sequence) چندنویسه‌ای محصور در کوتیشن تکی نمایش داده می‌شود. برای مثال،

'a'		// نویسه `a` در ASCII
'\0'		// یک بایت صفر
'\n'		// نویسه خط جدید در ASCII
'\33'		// نویسه گریز ASCII (هشت‌هشتی ۳۳)
'\x2b'	// مثبت در ASCII (شانزده‌شانزدهی 2b)
'\377'	// ۳۷۷ هشت‌هشتی = ۲۵۵ ده‌دهی، غیر ASCII

ثابت‌های نویسه‌ای درون دابل کوتیشن محصور می‌شوند. یک آرایهٔ نویسه‌ای می‌تواند به صورت یک رشته محصور در دابل کوتیشن نمایش داده شود. قواعد معمول گریز رشته در زبان C معتبر هستند. برای مثال

"a"		// نویسه `a` در ASCII
"Two\nlines\n"	// یک رشته ۱۰ نویسه‌ای با دو خط جدید تعبیه‌شده
"a bell:\007"	// رشته‌ای حاوی زنگ ASCII

ثابت‌های عدد صحیح short برای نمایش مقادیر ۱۶ بیتی علامت‌دار در نظر گرفته شده‌اند. شکل یک ثابت short به صورت یک ثابت عدد صحیح است که یک `s' یا `S' به آن ضمیمه شده است. اگر یک ثابت short با `0' شروع شود، به عنوان هشت‌هشتی تفسیر می‌شود، به جز زمانی که با `0x' آغاز شود که در این صورت به عنوان یک ثابت شانزده‌شانزدهی تفسیر می‌گردد. برای مثال:

-2s	// مقدار -2 از نوع short
0123s	// هشت‌هشتی (octal)
0x7ffs  //شانزده‌شانزدهی (hexadecimal)

ثابت‌های عدد صحیح Long برای نمایش مقادیر ۳۲ بیتی علامت‌دار در نظر گرفته شده‌اند. شکل یک ثابت long به صورت یک ثابت عدد صحیح معمولی است، اگرچه ضمیمه کردن یک `l' یا `L' اختیاری نیز قابل قبول است. اگر یک ثابت long با `0' شروع شود، به عنوان هشت‌هشتی تفسیر می‌شود، به جز حالتی که با `0x' شروع شود که به عنوان یک ثابت شانزده‌شانزدهی تفسیر می‌گردد. مثال‌هایی از ثابت‌های معتبر long عبارتند از:

-2
1234567890L
0123		// هشت‌هشتی (octal)
0x7ff		// شانزده‌شانزدهی (hexadecimal)

ثابت‌های ممیز شناور از نوع float برای نمایش داده‌های ممیز شناور با حدود هفت رقم بااهمیت دقت مناسب هستند. شکل یک ثابت float مشابه یک ثابت ممیز شناور زبان C است که یک `f' یا `F' به انتهای آن افزوده شده است. برای مثال موارد زیر همگی ثابت‌های قابل قبول float هستند:

-2.0f
3.14159265358979f	// به دقت کمتری کوتاه خواهد شد
1.f

ثابت‌های ممیز شناور از نوع double برای نمایش داده‌های ممیز شناور با حدود شانزده رقم بااهمیت دقت مناسب هستند. شکل یک ثابت double همانند یک ثابت ممیز شناور در C است. یک `d' یا `D' اختیاری می‌تواند به آن ضمیمه شود. برای مثال موارد زیر همگی ثابت‌های قابل قبول double هستند:

-2.0
3.141592653589793
1.0e-20
1.d