The CDF_VARGET procedure reads multiple values from a Common Data Format file variable. By default, all elements of a record are read. If INTERVAL and/or OFFSET are specified but no COUNT is specified, CDF_VARGET attempts to get as many elements of each record as possible.

Examples

; Create a CDF file,  and make a few variables:
id = CDF_CREATE('DEMOvargets')
vid1 = CDF_VARCREATE(id, 'VAR1', /CDF_CHAR, NUMELEM=15)
vid2=CDF_VARCREATE(id, 'VAR2', /CDF_UCHAR, NUMELEM=10)
CDF_VARPUT, id, vid1, BINDGEN(15, 2)+55, COUNT=2
CDF_VARPUT, id, vid2, ['IDLandCDF ', 'AreWayCool'
 
; Retrieve the CDF_CHAR array as byte data:
CDF_VARGET, id,'VAR1',var1_byte,REC_COUNT=2
HELP, var1_byte 
 
;Retrieve the CDF_CHAR array as string data:
CDF_VARGET, id, 'VAR1', var1_string, REC_COUNT=2, /STRING
HELP, var1_string
 
; For demonstration purposes, use the 'VAR2' variable number to
; access 'VAR2' for the duration of this example:
 
var2num = CDF_VARNUM(id, 'VAR2')
HELP, var2num
 
; Rename 'VAR2' to 'VAR_STRING_2':
CDF_VARRENAME, id, var2num, 'VAR_STRING_2'
 
; Examine VAR_STRING_2 with CDF_VARINQ:
VAR2_INQ = CDF_VARINQ(id, var2num)
HELP, VAR2_INQ, /STRUCTURE
 
; Read in and print out VAR_STRING_2:
CDF_VARGET, id, var2num, var2_string, /STRING, REC_COUNT=2
PRINT, var2_string
 
CDF_DELETE, id ; Delete the CDF file

IDL Output

% CDF_VARGET: Warning: converting data to unsigned bytes

This warning message indicates that the data was stored in the CDF file with type CDF_CHAR (signed 1-byte characters), but was retrieved by IDL with type BYTE (unsigned byte). To turn this warning message off, set !QUIET=1.

VAR1_BYTE       BYTE      = Array(15,  2)
 
VAR1_STRING     STRING    = Array(2)
 
VAR2NUM         LONG      =            1
 
** Structure <400b1600>, 6 tags, length=33, refs=1:
   IS_ZVAR         INT                    0
   NAME            STRING     'VAR_STRING_2'
   DATATYPE        STRING        'CDF_UCHAR'
   NUMELEM         LONG                   10
   RECVAR          STRING             'VARY'
   DIMVAR          BYTE                    0
 
IDLandCDF  AreWayCool

Syntax

CDF_VARGET, Id, Variable, Value [, COUNT=vector] [, INTERVAL=vector] [, OFFSET=vector] [, REC_COUNT=records] [, REC_INTERVAL=value] [, REC_START=record] [, /STRING] [, /TO_COLUMN_MAJOR] [, /ZVARIABLE]

Arguments

Id

The CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE

Variable

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

Value

A named variable in which the values of the variable are returned.

Keywords

COUNT

An optional vector containing the counts to be used in reading Value. The default is to read all elements in each record, taking into account INTERVAL and OFFSET.

INTERVAL

A vector specifying the interval between values in each dimension. The default value is 1 for each dimension.

OFFSET

A vector specifying the array indices within the specified record(s) at which to begin writing. OFFSET is a 1-dimensional array containing one element per CDF dimension. The default value is zero for each dimension.

REC_COUNT

The number of records to read. The default is 1.

REC_INTERVAL

The interval between records when reading multiple records. The default value is 1.

REC_START

The record number at which to start reading. The default is 0.

STRING

Set this keyword to return CDF_CHAR and CDF_UCHAR data from the CDF file into Value as string data rather than byte data. This keyword is ignored if the data in the CDF file 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-compilant CDF file, the dimensions defined in the meta-data (DEPEND_1, DEPEND_2, etc.) will match the returned data. This keyword is only applicable when reading full variable records.

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.

Examples

; Create a CDF file,  and make a few variables:
id = CDF_CREATE('DEMOvargets')
vid1 = CDF_VARCREATE(id, 'VAR1', /CDF_CHAR, NUMELEM=15)
vid2=CDF_VARCREATE(id, 'VAR2', /CDF_UCHAR, NUMELEM=10)
CDF_VARPUT, id, vid1, BINDGEN(15, 2)+55, COUNT=2
CDF_VARPUT, id, vid2, ['IDLandCDF ', 'AreWayCool'
 
; Retrieve the CDF_CHAR array as byte data:
CDF_VARGET, id,'VAR1',var1_byte,REC_COUNT=2
HELP, var1_byte 
 
;Retrieve the CDF_CHAR array as string data:
CDF_VARGET, id, 'VAR1', var1_string, REC_COUNT=2, /STRING
HELP, var1_string
 
; For demonstration purposes, use the 'VAR2' variable number to
; access 'VAR2' for the duration of this example:
 
var2num = CDF_VARNUM(id, 'VAR2')
HELP, var2num
 
; Rename 'VAR2' to 'VAR_STRING_2':
CDF_VARRENAME, id, var2num, 'VAR_STRING_2'
 
; Examine VAR_STRING_2 with CDF_VARINQ:
VAR2_INQ = CDF_VARINQ(id, var2num)
HELP, VAR2_INQ, /STRUCTURE
 
; Read in and print out VAR_STRING_2:
CDF_VARGET, id, var2num, var2_string, /STRING, REC_COUNT=2
PRINT, var2_string
 
CDF_DELETE, id ; Delete the CDF file

IDL Output

% CDF_VARGET: Warning: converting data to unsigned bytes

This warning message indicates that the data was stored in the CDF file with type CDF_CHAR (signed 1-byte characters), but was retrieved by IDL with type BYTE (unsigned byte). To turn this warning message off, set !QUIET=1.

VAR1_BYTE       BYTE      = Array(15,  2)
 
VAR1_STRING     STRING    = Array(2)
 
VAR2NUM         LONG      =            1
 
** Structure <400b1600>, 6 tags, length=33, refs=1:
   IS_ZVAR         INT                    0
   NAME            STRING     'VAR_STRING_2'
   DATATYPE        STRING        'CDF_UCHAR'
   NUMELEM         LONG                   10
   RECVAR          STRING             'VARY'
   DIMVAR          BYTE                    0
 
IDLandCDF  AreWayCool

Version History

 

Pre 4.0

Introduced
8.3 Added TO_COLUMN_MAJOR keyword