The CDF_READVARIABLE function reads full information from a Common Data Format 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).

Examples


The following examples show how CDF_READVARIABLE can be used.

 
; 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')
 
; Or, it can be called this way
var = CDF_READVARIABLE('a1_k0_mpa_20050804_v02', 'Epoch')
 
; Show the keys
var.keys()
[
  "VarInfo",
  "VarAttrs",
  "VarData"
]
 
; Show the variable's basic information
PRINT, var['VarInfo']
DataType: CDF_EPOCH
NumElems:            1
RecVary: VARY
NumDims:            2
DimSizes:            2           3
DimVary: NOVARY ...
NumWrittenRecs:          991
 
; Show the dimensional variances
PRINT, var['VarInfo', 'DimVary']
NOVARY NOVARY
 
; Show the variable attributes
PRINT, var['VarAttrs']
FIELDNAM: Time
VALIDMIN:        62879846400000.000
VALIDMAX:        63776678399000.000
SCALEMIN:        62879846400000.000
SCALEMAX:        63776678399000.000
CATDESC: Time of proton collection (electrons 21.5 seconds later)
UNITS: ms
MONOTON: INCREASE
FILLVAL:   -9.9999999999999996e+30
VAR_TYPE: support_data
DICT_KEY:
LABLAXIS: Epoch
AVG_TYPE:
DISPLAY_TYPE:
VAR_NOTES:
 
; Show the variable data
PRINT, var['VarData']
6.3290333e+13   6.3290333e+13
6.3290333e+13   6.3290333e+13
6.3290333e+13   6.3290333e+13
6.3290333e+13   6.3290333e+13
6.3290333e+13   6.3290333e+13
6.3290333e+13   6.3290333e+13
6.3290333e+13   6.3290333e+13
6.3290333e+13   6.3290333e+13
6.3290333e+13   6.3290333e+13
6.3290333e+13   6.3290333e+13
6.3290333e+13   6.3290333e+13
6.3290333e+13   6.3290333e+13
...
 
; Turn on the zmode and encode the attributes of CDF epoch types. Its
; numDims becomes 0.
var2 = CDF_READVARIABLE('a1_k0_mpa_20050804_v02', 0, /ENCODING, /ZMODE2)
 
; Non-varying dimensions are no shown...
PRINT, var2['VarInfo']
DataType: CDF_EPOCH
NumElems:            1
RecVary: VARY
NumDims:            0
NumWrittenRecs:          991
 
; Show the encoded data for attributes: VALIDMIN/VALIDMAX/SCALEMIN/SCALEMAX
PRINT, var2['VarAttrs']
FIELDNAM: Time
VALIDMIN: 1992-08-01T00:00:00.000
VALIDMAX: 2020-12-31T23:59:59.000
SCALEMIN: 1992-08-01T00:00:00.000
SCALEMAX: 2020-12-31T23:59:59.000
CATDESC: Time of proton collection (electrons 21.5 seconds later)
UNITS: ms
MONOTON: INCREASE
FILLVAL:   -9.9999999999999996e+30
VAR_TYPE: support_data
DICT_KEY:
LABLAXIS: Epoch
AVG_TYPE:
DISPLAY_TYPE:
VAR_NOTES:
 
; Each record is a scalar...
PRINT, var2['VarData']
6.3290333e+13
6.3290333e+13
6.3290333e+13
6.3290333e+13
6.3290333e+13
6.3290333e+13
...
 
; Show the metadata from variable 'Epoch' and encode the epoch data
CDF_READVARIABLE('a1_k0_mpa_20050804_v02', 'Epoch', /META, /ENCOD)
{
  "Epoch": {
    "FIELDNAM": "Time",
    "VALIDMIN": "1992-08-01T00:00:00.000",
    "VALIDMAX": "2020-12-31T23:59:59.000",
    "SCALEMIN": "1992-08-01T00:00:00.000",
    "SCALEMAX": "2020-12-31T23:59:59.000",
    "CATDESC": "Time of proton collection (electrons 21.5 seconds later)",
    "UNITS": "ms",
    "MONOTON": "INCREASE",
    "FILLVAL": -9.9999999999999996e+30,
    "VAR_TYPE": "support_data",
    "DICT_KEY": " ",
    "LABLAXIS": "Epoch",
    "AVG_TYPE": " ",
    "DISPLAY_TYPE": " ",
    "VAR_NOTES": " "
  }
}

Syntax


Result = CDF_READVARIABLE( Id, Variable [, /DATAONLY] [, /ENCODING] [, /INFO] [, REC_COUNT=...] [, REC_START=...] [, /STRING] [, /TO_COLUMN_MAJOR] [, /VARATTRS] [, /ZMODE2] [, /ZVARIABLE] )

Return Value


If successful, a hash with the requested information from the variable in a CDF is returned.

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.

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.

Variable

A string containing the name of the variable or the variable number being read.

Keywords


DATAONLY

Set this keyword to ignore the variable's basic information and attributes, but only read the variable's data. The key for the returned hash is the variable name.

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.

INFO

Set this keyword to read only the basic information from a CDF and all variables in it. The key for the returned hash is the variable name.

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 the variable's metadata. The key for the returned hash is the variable name. If there is no metadata for the variable, an empty hash is returned.

ZMODE2

Set the zMODE on so a rVariable is going to be handled as a zVariable and its non-varying dimension(s) will not be shown. ZMODE2 and ZVARIABLE are mutually exclusive.

ZVARIABLE

If Variable is a variable ID (as opposed to a variable name) and the variable is a zVariable, set this flag to indicate that the variable ID is a zVariable ID. The default is to assume that Variable is an rVariable ID. This keyword and ZMODE2 are mutually exclusive.

Version History


8.9

Introduced