CDF_READCDF =========== 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 value portion of the hash could be a hash itself, making the returned output a structure of hash of the hashes (HOHs). 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 value for the key: "CDFInfo" is another hash that provides basic information about the CDF. The value for the key: "GlobalAttrs" is a hash that contains the global attributes. Each element in the hash uses the global attribute name as the key and its value is again another hash. In this hash, each element has the entry number as the key and the entry as the value, a scalar or vector. The value for the key: "Variables" is a hash that contains the information for all variables. Each element is the hash is keyed by the variable name. The value of the element is again another hash with up to three (3) elements. The first element has the key of "VarInfo" with a value of a hash, which provides the specification about the variable. The second element has the key of "VarAttrs" with a value of a hash, which contains the variable attributes. Each element has the attribute name as the key and its attribute entry as its value, which can be a scalar or vector. The third element has the key: "VarData". Its value is an object for the retrieved variable data. The value for the key: "NoEntryAttrs", if it exists, is another hash with up two elements, each providing the name(s), as the value, of global or variable attributes that have no entry data. Those attribute names are presented in an vector. The variables keys are normally associated with attribute names, variable names and entry numbers. A sample of the returned of a full hash from a CDF looks like this: { "CDFInfo": { "FileName": "test", "NumGlobalAttrs": 5, "NumVariableAttrs": 5, "NumVariables": 2, "Format": "SINGLE_FILE", "Majority": "ROW_MAJOR", "Version": "3.8.1", ... ... ... }, "GlobalAttrs": { "Project": { 0: "LWS>Living With a Star" }, "Source_name": { 0: "RBSP-B>Radiation Belt Storm Probe B" }, "Discipline": { 0: "Space Physics>Magnetospheric Science" }, "Data_type": { 0: "H0>High Time Resolution" }, "TEXT": { ... ... ... } ... ... ... }, "Variables": { "Latitude": { "VarInfo": { "DataType": "CDF_UINT1", "NumElems": 1, "RecVary": "VARY", "NumDims": 1, "DimSizes": [3], ... ... }, "VarAttrs": { "VALIDMIN": -10, "VALIDMAX": 90, ... ... ... } "VarData": [[25, 54, 5], [15, 25, 35], [10, 28, 55]] }, "Longitude": { "VarInfo": { "DataType": "CDF_INT2", "NumElems": 1, "RecVary": "VARY", "NumDims": 1, "DimSizes": [3], ... ... }, "VarAttrs": { "VALIDMIN": 0, "VALIDMAX": 360, ... ... ... }, "VarData": [[100, 200, 300], [67, 32, 27], [10, 20, 30], ... } } } Examples ; Open a CDF file: file = 'rbsp-a_magnetometer_4sec-sm_emfisis-l3_20150622_v1.3.2.cdf' id = CDF_OPEN(file) ; Retrieve the CDF_CHAR array as byte data: cdf = CDF_READCDF (id, /string, /encoding) Or, it can be called this way: cdf = CDF_READCDF (file, /string, /encoding) ; Shows the keys cdf.keys() [ "CDFInfo", "GlobalAttrs", "Variables" ] ; Show the CDF's basic information cdf['CDFInfo'] { "FileName": "test3", "NumGlobalAttrs": 5, "NumVariableAttrs": 5, "NumVariables": 2, "Format": "SINGLE_FILE", "Majority": "ROW_MAJOR", "Version": "3.8.1", ... ... ... } ; Show global attributes cdf['GlobalAttrs'] { "Project": { 0: "LWS>Living With a Star" }, "Source_name": { 0: "RBSP-B>Radiation Belt Storm Probe B" }, "Discipline": { 0: "Space Physics>Magnetospheric Science" }, "Data_type": { 0: "H0>High Time Resolution" }, ... ... ... } ; Show the variables cdf['Variables'].keys() [ "Epoch", "UTC", "SCLOCK_Full", "OrbitNumber", "ET", "MidET", "StopET", ... ... ... ] ; Show Variable Epoch's information cdf['Variables', 'Epoch'].keys() [ "VarInfo", "VarAttrs", "VarData" ] ; Show Epoch's basic information cdf['Variables', 'Epoch', 'VarInfo'] { "DataType": "CDF_TIME_TT2000", "NumElems": 1, "RecVary": "VARY", "NumDims": 0, "NumWrittenRecs": 120148, "Compression": "GZIP.6" } ; Show Epoch's attributes cdf['Variables', 'Epoch', 'VarAttrs'] { "CATDESC": "Ephemeris Time of the start of the accumulation for this measurement.", "FIELDNAM": "Epoch", "FILLVAL": -9223372036854775808, "LABLAXIS": "Epoch", "UNITS": "ns", "VALIDMIN": -315575942816000000, "VALIDMAX": 946728067183000000, "VAR_TYPE": "support_data", "SCALETYP": "linear", "VAR_NOTES": "This is the Ephemeris Time ....", "MONOTON": "INCREASE", "TIME_BASE": "J2000", "TIME_SCALE": "Terrestrial Time", "REFERENCE_POSITION": "Rotating Earth Geoid" } ; Show Epoch's data cdf['Variables', 'Epoch', 'VarData'] 465480068230000000 465480068831000000 465480069433000000 465480070035000000 465480070637000000 465480071238000000 465480071840000000 ... ... ... If there are no global attributes or variable attributes, then nothing will be returned for hash GlobalAttrs or VarAttrs, respectively. Note: This function will operate the CDF in zMODEon2 mode, which means all rVariables are handled as zVariables by removing those non-varying dimensions from each rVAriabale. And, the zVariable ids are renumbered, after the rVariables'. If the CDF has only one type of variables, then the variable ids are not affected. Syntax cdf = CDF_READCDF ( Id, [, /DATAONLY] [, /ENCODING] [, /GLOBALS] [, /STRING] [, /INFO] [, /METADATA] [, /NOENTRY] [, /VARATTRS] [, /TO_COLUMN_MAJOR] [, VARS=...] [, REC_COUNT=...] [, REC_START=...] ) Return Value If successful, a hash with the requested information from a CDF is returned. Arguments Id The CDF name or ID (returned from a previous call to CDF_OPEN or CDF_CREATE). If a CDF name is entered, the file will be closed after the operation is done. Keywords DATAONLY Set this keyword to read all variables' data, ignoring the basic information and metadata. The keys for the returned hash are the variable names. ENCODING Set this keyword to encode the variable's attributes or basic information. It will convert variable's pad value or attributes' data to an encoded form. This is mainly used for the values of CDF epoch type. GLOBALS Set this keyword to read only the global attributes from the CDF. The keys for the returned hash are the global attribute names. If there is no global attribute, an empty hash is returned. INFO Set this keyword to read the basic information about the CDF and all variables' specifications in it. METADATA Set this keyword to read only the metadata, the global attributes and variables' attributes, from the CDF. NOENTRY Set this keyword to find out which global and variable attributes are defined, but do not have any entry data. If there is no such attribute, an empty hash is returned. REC_COUNT Set this keyword to the number of records to read. If not specified, all records, starting from REC_START, will be read. At least one record will be returned, even it is a virtual record. REC_START Set this keyword to the starting record number to read. If not specified, the variable's first record, record number 0, is assumed. STRING Set this keyword to return a variable's data of CDF_CHAR or CDF_UCHAR type from the CDF file as a string rather than byte data. This keyword is ignored if the variable data is not of type CDF_CHAR or CDF_UCHAR. TO_COLUMN_MAJOR Set this keyword to convert the returned value from row-major form to column-major form. When this keyword is used with an ISTP-compliant CDF file, the dimensions defined in the variable attribute DEPEND_1, DEPEND_2, etc., will match the returned data. This keyword is only applicable when reading full variable records. VARATTRS Set this keyword to read only variable attributes for all or the selected variable(s) from the CDF. The keys for the returned hash are the variable names. If there is no metadata, an empty hash is returned. VARS Specify the variable(s) to be read. The field value can be a scalar or an array of values. The value can be either a variable name(s) or variable id(s). If a variable id(s) is used, make sure that zVariables' ids are properly renumbered, after the rVariables' ids, if the CDF has both types of variables. Only the information, variable's specification, metadata and/or data, from the specified variable(s) will be returned. Version History Post 8.3 Introduced © 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris Corporation. All Rights Reserved. This information is not subject to the controls of the International Traffic in Arms Regulations (ITAR) or the Export Administration Regulations (EAR). However, this information may be restricted from transfer to various embargoed countries under U.S. laws and regulations.