The CDF_CONTROL procedure allows you to obtain or set information for a Common Data Format file, its variables, and its attributes.

Syntax

---

CDF_CONTROL, Id [, ATTRIBUTE=name or number] [, GET_ATTR_INFO=variable] [, GET_CACHESIZE=variable] [, GET_COPYRIGHT=variable] [, GET_FILENAME=variable] [, GET_FORMAT=variable] [, GET_LEAPSECONDLASTUPDATED=variable] [, GET_NEGTOPOSFP0_MODE=variable] [, GET_NUMATTRS=variable] [, GET_READONLY_MODE=variable] [, GET_RVAR_CACHESIZE=variable] [, GET_SPARSERECORDS=variable] [, GET_VAR_INFO=variable] [, GET_ZMODE=variable] [, GET_ZVAR_CACHESIZE=variable] [, SET_CACHESIZE=value] [, SET_EXTENDRECS=records] [, SET_INITIALRECS=records] [, SET_LEAPSECONDLASTUPDATED=value] [, /SET_NEGTOPOSFP0_MODE] [, SET_PADVALUE=value] [, /SET_READONLY_MODE] [, SET_RVAR_CACHESIZE=value{See Note}] [, SET_RVARS_CACHESIZE=value{See Note}] [, SET_SPARSERECORDS=variable] [, SET_ZMODE={0 | 1 | 2}] [, SET_ZVAR_CACHESIZE=value{See Note}] [, SET_ZVARS_CACHESIZE=value{See Note}] [, VARIABLE=name or index] [, /ZVARIABLE]

Note: Use only with MULTI_FILE CDF files

Arguments

---

Id

The CDF ID of the file being changed or queried, as retuned from a previous call to CDF_OPEN or CDF_CREATE.

Keywords

---

ATTRIBUTE

Makes the attribute specified the current attribute. Either an attribute name or an attribute number may be specified.

GET_ATTR_INFO

Set this keyword to a named variable that will contain information about the current attribute. Information is returned in the form of a structure with the following tags:

{ NUMGENTRIES:0L, NUMRENTRIES:0L, NUMZENTRIES:0L, 

  MAXGENTRY:0L, MAXRENTRY:0L, MAXZENTRY:0L }

The first three tags contain the number of globals, rVariables, and zVariables associated with the attribute. MAXGENTRY contains the highest index used, and the last two tags contain the highest variable ids that were used when setting the attribute’s value.

Note that an attribute must be set before GET_ATTR_INFO can be used. For example:

CDF_CONTROL, id, ATTRIBUTE='ATT1', GET_ATTR_INFO=X

GET_CACHESIZE

Set this keyword to a named variable that will be set equal to the number of 512-byte cache buffers being used for the current.cdf file. For discussion about using caches with CDF files, see “Caching Scheme” in the CDF User’s Guide.

GET_COPYRIGHT

Set this keyword to a named variable that will contain the copyright notice of the CDF library now being used by IDL (as opposed to the library that was used to write the current CDF).

GET_FILENAME

Set this keyword to a named variable that will contain the pathname of the current .cdf file.

GET_FORMAT

Set this keyword to a named variable that will contain a string describing the CDF Format of the current CDF file. Possible formats are SINGLE_FILE and MULTI_FILE, and can only be set with the CDF_CREATE procedure. For example:

id = CDF_CREATE('single', /SINGLE_FILE)

CDF_CONTROL, id, GET_FORMAT = cdfformat

HELP, cdfformat

IDL prints:

CDFFORMAT      STRING    = 'SINGLE_FILE'

GET_LEAPSECONDLASTUPDATED

Set this keyword to a named variable in which to return the date the leap second was last updated, in YYYYMMDD form, e.g., 20150701, as a 32-bit integer. This information is only relevant to CDF TT2000 variable data. Its value represents the latest leap second that was added to the leap second table when this CDF was created. This value can also be 0, meaning the table was not used to create the CDF, or –1 for older CDFs that have not had the field set.

GET_NEGTOPOSFP0_MODE

Set this keyword to a named variable that will be set equal to the CDF negative to positive floating point 0.0 (NEGtoPOSfp0) mode. In NEGtoPOSfp0 mode, values equal to -0.0 will be converted to 0.0 whenever encountered. By CDF convention, a returned value of -1 indicates that this feature is enabled, and a returned value of zero indicates that this feature is disabled.

GET_NUMATTRS

Set this keyword to a named variable that will contain a two-element array of longs. The first value will contain the number of attributes with global scope; the second value will contain the number of attributes with variable scope. NOTE: attributes with GLOBAL_SCOPE_ASSUMED scope will be included in the global scope count and attributes with VARIABLE_SCOPE_ASSUMED will be included in the count of attributes with variable scope.

Note that you can obtain the total number of attributes using the CDF_INQUIRE routine.

GET_READONLY_MODE

Set this keyword to a named variable that will be set equal to the CDF read-only mode. By CDF convention, a returned value of -1 indicates that the file is in read-only mode, and a returned value of zero indicates that the file is not in read-only mode.

GET_RVAR_CACHESIZE

Set this keyword to a named variable that will be set equal to the number of 512-byte cache buffers being used for the current MULTI_FILE format CDF and the rVariable indicated by the VARIABLE keyword. This keyword should only be used for MULTI_FILE CDF files. For discussion about using caches with CDF files, see “Caching Scheme” in the CDF User’s Guide.

GET_SPARSERECORDS

Set this keyword to a named variable that will be set equal to a string containing the variable's sparseness. Possible values are: "NO_SPARSERECORDS", "PAD_SPARSERECORDS", or "PREV_SPARSERECORDS".

GET_VAR_INFO

Set this keyword to a named variable that will contain information about the current variable. For detailed information about the returned values, see “Records” in the CDF User’s Guide. Information is returned in the form of a structure with the following tags:

{ EXTENDRECS:0L, MAXALLOCREC:0L, MAXREC:0L,

   MAXRECS:0L, NINDEXENTRIES:0L, NINDEXRECORDS:0L,

   PADVALUE:<as appropriate> }

The EXTENDRECS field will contain the number of records by which the current variable will be extended whenever a new record needs to be added.

The MAXALLOCREC field will contain the maximum record number (zero-based) allocated for the current variable. Records can only be allocated for NOVARY zVariables in SINGLE_FILE format CDFs. When these conditions are not met, the value is set to -1.

The MAXREC field will contain the maximum record number for the current variable. For variables with a record variance of NOVARY, this will be at most zero. A value of -1 indicates that no records have been written.

The MAXRECS field will contain the maximum record number (zero-based) of all variables of this type (rVariable or zVariable) in the current CDF. A value of -1 indicates that no records have been written.

The NINDEXENTRIES field will contain the number of index entries for the current variable in the current CDF. This value is -1 unless the current CDF is of SINGLE_FILE format, and the variable is a zVariable.

The NINDEXRECORDS field will contain the number of index records for the current variable in the current CDF. This value is -1 unless the current CDF is of SINGLE_FILE format, and the variable is a zVariable.

The PADVALUE field will contain the value being used to fill locations that are not explicitly filled by the user. If a PADVALUE is not specified, CDF_CONTROL returns an error.

For example:

fid = CDF_CREATE('test.cdf')

varid = CDF_VARCREATE(fid, 'test')

CDF_CONTROL, fid, GET_VAR_INFO=info, VARIABLE='test'

IDL Prints:

% CDF_CONTROL: Function completed but 

NO_PADVALUE_SPECIFIED: A pad value has not been specified.

GET_ZMODE

Set this keyword to a named variable that will be set equal the zMode of the current CDF. In a non-zero zMode, CDF rVariables are temporarily replaced with zVariables. The possible return values are:

• 0 = zMode is off.
• 1 = zMode is on in zMode/1, indicating that the dimensionality and variances of the variables will stay the same.
• 2 = zMode is on in zMode/2, indicating that those dimensions with false variances (NOVARY) will be eliminated.

For Information about zModes, see “CDF Modes” in the CDF User’s Guide.

GET_ZVAR_CACHESIZE

Set this keyword to a named variable that will be set equal to the number of 512-byte cache buffers being used in the current MULTI_FILE format CDF and the zVariable indicated by the VARIABLE keyword. This keyword should only be used with MULTI_FILE CDF files. For discussion about using caches with CDF files, see “Caching Scheme” in the CDF User’s Guide.

SET_CACHESIZE

Set this keyword equal to the desired number of 512-byte cache buffers to used for the current .cdf file. For discussion about using caches with CDF files, see “Caching Scheme” in the CDF User’s Guide.

SET_EXTENDRECS

Set this keyword equal to the number of additional physical records that should be added to the current variable whenever it needs to be extended.

SET_INITIALRECS

Set this keyword equal to the number of records that should be initially written to the current variable. Note that this keyword should be set before writing any data to the variable.

SET_LEAPSECONDLASTUPDATED

Set this keyword to a 32-bit integer containing the date the leap second was last updated, in the form YYYYMMDD, e.g., 20150701. This information is only relevant to CDF TT2000 variable data. Its value must be a valid entry in the currently used leap second table, or zero (0), meaning the table is not being used.

SET_NEGTOPOSFP0_MODE

Set this keyword to a non-zero value to put the current CDF file into negative to positive floating point 0.0 (NEGtoPOSfp0) mode. In this mode, values equal to -0.0 will be converted to 0.0 whenever encountered. Setting this keyword equal to zero takes the current CDF file out of NEGtoPOSfp0 mode.

SET_PADVALUE

Set this keyword equal to the pad value for the current variable.

SET_READONLY_MODE

Set this keyword to a non-zero value to put the current CDF file into read-only mode. Set this keyword equal to zero to take the current CDF file out of read-only mode.

SET_RVAR_CACHESIZE

Set this keyword equal to the desired number of 512-byte cache buffers to used for the rVariable file specified by the VARIABLE keyword. This keyword should only be used with MULTI_FILE CDF files. For discussion about using caches with CDF files, see “Caching Scheme” in the CDF User’s Guide.

SET_RVARS_CACHESIZE

Set this keyword equal to the desired number of 512-byte cache buffers to used for all rVariable files in the current CDF file or files. This keyword should only be used with MULTI_FILE CDF files. For discussion about using caches with CDF files, see “Caching Scheme” in the CDF User’s Guide.

SET_SPARSERECORDS

Set this keyword equal to an integer or string containing the sparserecords value for the current variable. Valid values are: 0 or "NO_SPARSERECORDS", 1 or "PAD_SPARSERECORDS", 2 or "PREV_SPARSERECORDS". For discussion about using sparseness with CDF files, see "Sparseness" in the CDF User's Guide, available on the NASA CDAWeb website.

SET_ZMODE

Set this keyword to change the zMode of the current CDF. In a non-zero zMode, CDF rVariables are temporarily replaced with zVariables. Set this keyword to one (1) to change to zMode/1, in which the dimensionality and variances of the variables stay the same. Set this keyword to two (2) to change to zMode/2, in which those dimensions with false variances (NOVARY) are eliminated. For Information about zModes, see “CDF Modes” in the CDF User’s Guide.

SET_ZVAR_CACHESIZE

Set this keyword equal to the desired number of 512-byte cache buffers to used for the zVariable’s file specified by the VARIABLE keyword. This keyword should only be used with MULTI_FILE CDF files. For discussion about using caches with CDF files, see “Caching Scheme” in the CDF User’s Guide.

SET_ZVARS_CACHESIZE

Set this keyword equal to the desired number of 512-byte cache buffers to used for all zVariable files in the current CDF. This keyword should only be used with MULTI_FILE CDF files. For discussion about using caches with CDF files, see “Caching Scheme” in the CDF User’s Guide.

VARIABLE

Set this keyword to a name or index to set the current variable. The following example specifies that the variable MyData should have 20 records written to it initially:

CDF_CONTROL, id, VAR='MyData', SET_INITIALRECS=20

Note that if VARIABLE is set to the index of a zVariable, the ZVARIABLE keyword must also be set. If ZVARIABLE is not set, the variable is assumed to be an rVariable.

ZVARIABLE

Set this keyword to TRUE if the current variable is a zVariable and is referred to by index. For example:

CDF_CONTROL, id, VARIABLE=0, /ZVARIABLE, GET_VAR_INFO=V

Version History

---

Pre 4.0	Introduced
8.5	Added GET_LEAPSECONDLASTUPDATED , GET_SPARSERECORDS, SET_LEAPSECONDLASTUPDATED, GET_SPARSERECORDS keywords

See Also

---

CDF_CREATE, CDF_INQUIRE