Suite of easy-to-use functions for Java/Perl/C#/IDL® to read the CDF in a single call

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. The CDF home page contains examples, documentation, FAQs, and tools - https://cdf.gsfc.nasa.gov/. The CDF User Guide is available at: /html/cdf_docs.html.

2.Java

The CDF Java Application Programming Interfaces (APIs) are based on the core CDF library’s Internal Interface, and they support a near complete set of the Internal Interface functions. The Java APIs only support zVariables and treats rVariables as zVariables. This is not a problem since zVariable is a superset of rVariable. In another words, with zVariables, you can do everything with rVariables and more, but not vice versa.

Example:

CDF cdf1, cdf2, cdf3;
CDF.setFileBackward(BACKWARDFILEon);
cdf1 = CDF.create("test1");
cdf2 = CDF.create("test2");
CDF.setFileBackward(BACKWARDFILEoff);
cdf3 = CDF.create("test3");

3.Perl

The Perl-CDF package includes two interfaces: Internal Interface and Standard Interface. The Standard Interface only covers limited functions that deal mainly with the older rVariables and their attributes in the CDF. This interface is mirrored the original functions that are covered in the C’s Standard Interface. The Internal Interface, based on the C’s Internal Interface, provides a complete suite of CDF functionality.

The Quick Interface functions represent a set of easy to use functions that are based on Internal Interface to acquire information from the CDF library, a CDF file, its variable and variable data. Normally, a few basic calls to Internal Interface calls are needed to accomplish a function. These functions perform the basics for users so the data can be returned easily.

Example:

CDFgetLIBInfo returns the currrent library version, release and increment information, along with the leap second table information. The latest leap second added to the leap second table is returned. Both fields are presented in a Perl Hash object. The following example shows how the current CDF library and the leap second table are used.

.
.
.
my $status; # Returned status code.
my %info; # Returned hash.
.
.
($status, %info) = CDF::CDFgetLIBInfo();
UserStatusHandler (“1.0”. $status) if ($status < CDF_OK);
print Dumper(\%info);
$VAR1 = {
 'LATEST_LEAPSECOND_IN_TABLE' => 20170101,
 'LIB_VERSION' => '3.8.0'
118
 };

4.C#

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 provides commonly used constants that mimic to those defined in the .DLL CDFException provides the exception handling when a failed CDF operation is detected.

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, metadat and data. Each functions is made of calls from other lower-level functions.

Example:

.
void*          id;            /* CDF identifier. */
int            status;       /* Returned status code. */
Dictionary     cdf;         /* Retrieved information. */
.
.
try {
 …
 status = CDFopen (“test”, &id);
cdf = ReadCDFInfo (id);
 CDFUtils.PrintDictionary (cdf);
…
…
} catch (CDFException ex) {
 …
}

5.IDL

CDF is supported by commercial and open source data analysis/visualization software such as Interactive Data Language (IDL). The CDF_READCDF function reads information from a Common Data Format file. The retrieved information is presented in an IDL® hash form. The hash consists of up to four key/value pairs:

• The file’s basic information
• Global attributes
• Variables’ information, which includes variable’s specification, attributes and data
• Attributes without any data

The keys in key/value pair are either fixed keys or variable keys. They are all case-sensitive strings or numbers (as for global entry number). The fixed keys include “CDFInfo”, “GlobalAttrs”, “Variables” and “NoEntryAttrs” at the very top of the returned hash. In the middle, they are “VarInfo”, “VarAttrs” and “VarData” for each retrieved variable. There are also other fixed keys, e.g., “Version”, “Format”, “DataType”, “NumDims”, etc., in the lower level hash for CDF or variable specification information.

The CDF_READVARIABLE function reads full information from a CDF file’s variable. The information includes the basic information, variable attributes and all data. The retrieved info will be in a key/value hash table. The value(s) can be a nested hash of hashes (HOHs). There are fixed keys and variable keys. They are all case-sensitive strings. The fixed keys include VarInfo, VarAttrs and VarData. The variables keys are variable attribute names and variable names.

Example:

; Open a CDF file (with rVariables of 2-by-3 dimensionality):
id = CDF_OPEN('a1_k0_mpa_20050804_v02')
; Retrieve the full information for variable: 'Epoch'
var = CDF_READVARIABLE (id, 'Epoch')
var.keys()
[
"VarInfo",
"VarAttrs",
"VarData"