CDF_VARCREATE

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

In CDF, variable is a generic name for an object that represents data. Data can be scalar (0-dimensional) or multi-dimensional (up to 10-dimensional). Data does not have any associated scientific context; it could represent an independent variable, a dependent variable, a time and date value, an image, the name of an XML file, etc. You can describe a variable’s relationship to other variables via CDF’s attributes.

CDF supports two types of variables: zVariables and rVariables. Different zVariables in a CDF data set can have different numbers of dimensions and different dimension sizes. All rVariables in a CDF data set must have the same number of dimensions and the same dimension sizes; this is much less efficient than the zVariable storage mechanism. (rVariables were included in the original version of CDF, and zVariables were added in a later version to address the rVariables’ inefficient use of disk space.)

If you are working with a data set created using an early version of CDF, you may need to use rVariables. If you are creating a new CDF data set, use zVariables.

Examples

In this example, we create a variable, setting the data type from a string variable, which could have been returned by the DATATYPE keyword to a CDF_VARINQ call:

; create a file in IDL’s current directory

id = CDF_CREATE('temp.cdf')

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))

VarId1 = CDF_VARCREATE(id, "Zvar", /CDF_DOUBLE, /ZVARIABLE)

VarId2 = CDF_VARCREATE(id, "Zvar", [1,1,1], $

   /CDF_INT4, DIM=[10,20,30])

CDF_CLOSE, id ; Close the CDF file.

Syntax

Result = CDF_VARCREATE(Id, Name [, DimVary] [, /VariableType] [, ALLOCATERECS=records] [, DIMENSIONS=array] [, NUMELEM=characters] [, /REC_NOVARY | , /REC_VARY] [, /ZVARIABLE] )

Return Value

Returns the variable of the type specified by the chosen keyword.

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

VariableType

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

CDF_BYTE

CDF_CHAR

CDF_DOUBLE

(same as CDF_REAL8)

CDF_EPOCH

CDF_LONG_EPOCH

(see note below)

CDF_FLOAT

(same as CDF_REAL4)

CDF_INT1

CDF_INT2

CDF_INT4

CDF_INT8

CDF_REAL4

CDF_REAL8

CDF_UCHAR

CDF_UINT1

CDF_UINT2

CDF_UINT4

CDF_TIME_TT2000

If no type is specified, CDF_FLOAT is assumed.

Note: The keyword associated with the CDF_EPOCH16 variable type is CDF_LONG_EPOCH. The keyword name differs from the variable type name to avoid a keyword-name conflict with the CDF_EPOCH keyword. All other references to the CDF_EPOCH16 variable type use the variable type name.

Note: CDF_TIME_TT2000 is the nano-seconds since J2000 with leap seconds. It uses the same IDL data type as CDF_INT8, IDL_TYP_LONG64. If you use an attribute entry of CDF_TIME_TT2000, be sure to set the /CDF_EPOCH keyword for the CDF_ATTPUT call.

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 ensures that variable data is stored contiguously in the CDF file. For discussion about allocating records, see “Records” in the CDF User’s Guide.

DIMENSIONS

Set this keyword to create a new zVariable with the specified dimensions. If this keyword is not set, the variable is assumed to be a scalar. For example:

id = CDF_CREATE("cdffile.cdf")

zid = CDF_VARCREATE(id, "Zvar", [1,1,1], $

   DIM=[10,20,30], /CDF_INT4)

Note: Variables created with the DIMENSIONS keyword set are always zVariables.

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

Set this keyword to create a zVariable. For example:

id = CDF_CREATE("cdffile.cdf")

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

Note: zVariables are much more efficient than rVariables in their use of disk space. Unless the recipient of your data set is using a very early version of CDF, you should always create zVariables.