How to Use CDFs in C#

1.Introduction

Common Data Format (CDF) is a conceptual data abstraction for storing, manipulating, and accessing multidimensional datasets. CDF is referred to as a data abstraction because the actual physical format in which datasets are stored is not discussed. Instead, the form of the datasets and the means (interface) by which they may be manipulated are described. C#-CDF distribution is packaged in a self-extracting installer. Once the installer is downloaded and run, all distributed files, i.e., APIs, test programs, batch files, help information and the document, will be placed into a directory of choice. The CDF home page contains examples, documentation, FAQs, and tools - https://cdf.gsfc.nasa.gov/. The CDF User Guide and CDF C# Reference Manual are available at: /html/cdf_docs.html.

2.Easy to Use Read Functions

There is a set of easy to use, read functions that each will return an object of C#’s Dictionary, a set of key/value pairs. The key is either a string or an integer. The value can be a generic scalar or array of value of integer, floating value, or string, or another dictionary (of dictionaries). The returned information covers CDF basic information, global attributes, and variables’ specification, metadata and data. Each function is made of calls from other lower-level functions.

3.CDF Applications

Several classes are created for C# applications that facilitate the calls to the native CDF .DLL. The CDF namespace has been set up to include these CDF related classes: CDFConstants, CDFException, CDFAPIs. and CDFUtils. CDFConstants provide commonly used constants that mimic to those defined in the .DLL CDFException provides the exception handling when a failed CDF operation is detected. CDFAPIs provide all (static) public (and private) methods that C# applications can call to interact with the similar, underlining functions provided by the CDF Standard Interface in the .DLL. CDFUtils provides several small utility tools. These classes are distributed in the form of signed assemblies, as .DLLs. To facilitate the access to functions in DLL, each C# application must use the “cdf” namespace in order to call the C#-CDF APIs. CDFAPIs is the main class that provides the C#-CDF APIs. Class CDFAPIs inherits from CDFConstants class, which defines all constants referenced by the CDF. A C# application, if inheriting from the CDFAPIs class, can call all CDFAPIs methods and refer CDFConstants’ constants directly, without specifying their class names. CDFException class inherits from C#’s Exception class and CDFUtils class inherits from CDFConstants class as well.

4.Making Executables

If a test application, e.g., TestCDF.cs, resides in the same directory as all distributed .dll files, the following command can be used to create an executable:

csc /unsafe /platform:x86 /r:CDFAPIs.dll,CDFException.dll,
 CDFConstants.dll,CDFUtils.dll TestCDF.cs 

csc.exe, the C# compiler, can be called automatically from an IDE such as Visual Studio
.NET, or run from the command line if the PATH environment variable is set properly.
csc.exe can be found in the Windows’s .NET Framework directory,
<windows>\Microsoft.NET\Framework\v#.# (v#.# as v3.5 or in the latest release version). 

/unsafe option is required as pointers are used by C# applications to communicate with the CDF APIs and .DLL. /platform:x86 option is required for the Windows running 64-bit OS as C#-CDF is built on an x86 (32-bit) platform.

When the C#-CDF package is installed, the PATH environment variable is automatically modified to include the installation directory so the native CDF .DLL, dllcdfcsharp.dll , becomes available when a C# application calls CDF functions. Once the executable, TestCDF.exe, is created, it can be run from any directory.

If the C# applications that call CDF APIs reside in the directories other than the C#- CDF installation directory, the following compilation command can be used to create an executable (.exe):

csc /unsafe /platform:x86
 /lib:%CsharpCDFDir%
 /r:cdfapis.dll,cdfconstants.dll,cdfexception.dll,cdfutils.dll
 TestCDF.cs 

where environment variable CsharpCDFDir, the installation directory for C#-CDF package, is set when the installer is run.