CDF_VARCREATE

The CDF_VARCREATE function creates a new variable in a Common Data Format file.

Calling Sequence

Result = CDF_VARCREATE( Id, Name [, DimVary] )

Arguments

Id

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

Name

A string containing the name of the variable to be created.

DimVary

A one-dimensional array containing one element per CDF dimension. If the element is non-zero or the string 'VARY' , the variable will have variance in that dimension. If the element is zero or the string 'NOVARY' then the variable will have no variance with that dimension. If the variable is zero-dimensional, this argument may be omitted.

Keywords

You must specify the type variable being created. This is done by setting one of the following keywords:

If no type is specified, CDF_FLOAT is assumed.

Although all CDF variable types are supported within the file, IDL has full support only for the following CDF data types: CDF_DOUBLE, CDF_EPOCH, CDF_FLOAT, CDF_INT2, CDF_INT4, CDF_REAL4, CDF_REAL8, and CDF_UCHAR.

ALLOCATERECS

Set this keyword equal to the desired number of pre-allocated records for this variable in a SINGLE_FILE CDF file. Pre-allocating records ensure that variable data is stored contiguously in the CDF file. For discussion about allocating records, see section 2.3.8 ("Records") of the version 2.6 CDF User's Guide .

DIMENSIONS

Set this keyword to create a new zVariable with the specified dimensions. For example:

id = CDF_CREATE("cdffile.cdf", [100] )

zid = CDF_VARCREATE(id, "Zvar", [1,1,1], DIM=[10,20,30])

NUMELEM

The number of elements of the data type at each variable value. This keyword only has meaning for string data types (CDF_CHAR, CDF_UCHAR). This is the number of characters in the string. The default is 1.

REC_NOVARY

If this keyword is set, all records will contain the same information.

REC_VARY

If this keyword is set, all records will contain unique data. This is the default.

ZVARIABLE

A variable is assumed to be a zVariable if its dimensions are specified by the DIMENSIONS keyword. Set this keyword to create a zero-dimensional zVariable.

For example:

id = CDF_CREATE("cdffile.cdf", [100] )

zid = CDF_VARCREATE(id, "Zvar", /ZVARIABLE)

Example

Create a CDF file to record the data retrieved from an array of temperature and salinity detectors. In this example, there is a 3 x 4 array of detectors at two depths, 10.0 meters and 20.2 meters:

id = CDF_CREATE("temp_salinity.cdf", [3,4], /NETWORK_ENCODING, $

    /SUN_DECODING, /CLOBBER)

temp_id =CDF_VARCREATE(id, "Temperature", ['Vary', 'Vary'], $

    /REC_VARY,/CDF_FLOAT)

depth_id = CDF_VARCREATE(id, "Depth", [0,0], /REC_VARY, /CDF_FLOAT)

sal_id = CDF_VARCREATE(id, "Salinity", [1,1], /REC_VARY, $

    /CDF_DOUBLE)

Create and fill the UNITS attribute:

units_att = CDF_ATTCREATE(id, 'UNITS', /VARIABLE)

CDF_ATTPUT, id, 'UNITS', 'Depth', 'Meters'

CDF_ATTPUT, id, 'UNITS', temp_id, 'Kelvin'

CDF_ATTPUT, id, units_att, sal_id, 'Percent'

Create and write some fictitous data:

data1 = 20.0 + FINDGEN(3,4)

CDF_VARPUT, id, varid, data1

CDF_VARPUT, id, depth_id, '10.0' ; IDL will handle the type conversion, CDF will set all values of this record to a depth of 10.0.

CDF_VARPUT, id, depth_id, 20.2,rec_start=1
; Set the second depth.

CDF_VARPUT, id, sal_id, DINDGEN(3,4)/10.0
; Make more fictitous data.

Demostrate the non-variance of depth by retrieving the values. On the first pass, use CDF_VARGET1 to retrieve single values:

CDF_VARGET1, id, depth_id, pth_0 ; Get single values.

CDF_VARGET1, id, depth_id, depth_1, REC_START=1
; Get single values.

HELP, depth_0, depth_1

IDL prints:

DEPTH_0 FLOAT = 10.0000

DEPTH_1 FLOAT = 20.2000

Now retrieve the full depth records:

CDF_VARGET, id, depth_id, depth, REC_COUNT=2

Examine the depth variable

HELP, depth

IDL prints:

DEPTH FLOAT = Array(3, 4, 2)

PRINT, depth

IDL prints:

10.0000 10.0000 10.0000

10.0000 10.0000 10.0000

10.0000 10.0000 10.0000

10.0000 10.0000 10.0000

 

20.2000 20.2000 20.2000

20.2000 20.2000 20.2000

20.2000 20.2000 20.2000

20.2000 20.2000 20.2000

 

The following example creates a variable, setting the data type from a string variable, which could have been returned by the DATATYPE keyword to a CDF_VARINQ call.

VARTYPE = 'CDF_FLOAT'

Use the _EXTRA keyword and the CREATE_STRUCT function to make the appropriate keyword.

VarId = CDF_VARCREATE(Id, 'Pressure', [1,1], $

    NUMELEM=2, _EXTRA=CREATE_STRUCT(VARTYPE,1))

CDF_CLOSE, id ; Close the CDF file.