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, you should use zVariables.
Result = CDF_VARCREATE( Id, Name [, DimVary] [, /VariableType] [, ALLOCATERECS=records] [, DIMENSIONS=array] [, NUMELEM=characters] [, /REC_NOVARY | , /REC_VARY] [, /ZVARIABLE] )
Returns the variable of the type specified by the chosen keyword.
The CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE.
A string containing the name of the variable to be created.
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.
You must specify the type variable being created. This is done by setting one of the following keywords:
(same as CDF_REAL8)
(see note below)
(same as CDF_REAL4)
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.
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.
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.
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.
If this keyword is set, all records will contain the same information.
If this keyword is set, all records will contain unique data. This is the default.
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.
Note: Variables created with the DIMENSIONS keyword set are always zVariables.
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.
|
Pre 4.0 |
Introduced |
|
6.3 |
Add support for the CDF_EPOCH16 variable type |
|
6.4 |
Rename CDF_EPOCH16 keyword as CDF_LONG_EPOCH to avoid name conflict with CDF_EPOCH keyword. |