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

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

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

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

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

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

نام‌های ابعاد، متغیرها و ویژگی‌های CDL باید با یک نویسه الفبایی یا “_” آغاز شوند و نویسه‌های بعدی می‌توانند حروف یا ارقام یا “_” یا “-” باشند.

بخش اختیاری data در یک مشخصات CDL جایی است که متغیرهای netCDF می‌توانند مقداردهی اولیه شوند. نحو مقداردهی اولیه ساده است: نام یک متغیر، یک علامت مساوی و فهرستی از ثابت‌های جداشده با ویرگول (که احتمالاً با فاصله، تب و خطوط جدید از هم جدا شده‌اند) که با یک نقطه-ویرگول ختم می‌شود. برای آرایه‌های چندبُعدی، آخرین بُعد سریع‌ترین تغییر را دارد. بنابراین برای ماتریس‌ها ترتیب سطری (row-order) به جای ترتیب ستونی (column-order) استفاده می‌شود. اگر مقادیر کمتری نسبت به مقدار مورد نیاز برای پر کردن یک متغیر ارائه شود، با یک “مقدار پرکننده” (fill value) وابسته به نوع گسترش می‌یابد، که می‌تواند با ارائه مقداری برای یک ویژگی متمایز متغیر به نام “_FillValue” بازنویسی شود. نوع ثابت‌ها نیازی نیست با نوع اعلان‌شده برای متغیر مطابقت داشته باشد؛ تبدیل‌های نوع (coercions) به عنوان مثال برای تبدیل اعداد صحیح به ممیز شناور انجام می‌شوند. ثابت “_” می‌تواند برای تعیین مقدار پرکننده برای یک متغیر استفاده شود..SS "انواع داده‌های اولیه (Primitive Data Types)"

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

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

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

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

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

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

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

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

ثابت‌های اختصاص‌یافته به مشخصه‌ها یا متغیرها می‌توانند از هر یک از انواع پایه‌ای netCDF باشند. نحو (syntax) ثابت‌ها مشابه نحو C است، با این تفاوت که باید پسوندهای نوع به shortها و floatها اضافه شوند تا از longها و doubleها متمایز گردند.

یک ثابت byte با یک تک‌نویسه یا یک دنبالهٔ گریز چندنویسه‌ای که درون نقل‌قول‌های تکی محصور شده است، نمایش داده می‌شود. برای مثال:

'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

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

"a"             // ASCII `a'
"Two\nlines\n"  // a 10-character string with two embedded newlines
"a bell:\007"   // a string containing an ASCII bell

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

-2s      // a short -2
0123s    // octal
0x7ffs   //hexadecimal

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

-2
1234567890L
0123i         // octal
0x7ff         // hexadecimal

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

-2.0f
3.14159265358979f    // will be truncated to less precision
1.f
.1f

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

-2.0
3.141592653589793
1.0e-20
1.d