CDF_ATTCREATE
=============

The CDF_ATTCREATE function creates a new attribute in the specified Common 
Data Format file. If successful, the attribute ID is returned.

Examples

id = CDF_OPEN('test') ; Create a CDF file.

xx = CDF_ATTCREATE(id, 'Attribute-1', /GLOBAL_SCOPE)

CDF_ATTRENAME, id, 'Attribute-1', 'My Favorite Attribute'

PRINT, CDF_ATTNUM(id, 'My Favorite Attribute')

CDF_CLOSE, id ; Close the CDF file.

Syntax

Result = CDF_ATTCREATE( Id, Attribute_Name [, /GLOBAL_SCOPE] $
                                           [, /VARIABLE_SCOPE] )

Return Value

Returns the attribute ID.

Arguments

Id

The CDF ID of the file for which a new attribute is created, returned from a 
previous call to CDF_OPEN or CDF_CREATE.

Attribute_Name

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

Keywords

GLOBAL_SCOPE

Set this keyword to make the scope of the attribute global. This is the default.

VARIABLE_SCOPE

Set this keyword to indicate that the attribute’s scope is per variable.

Version History

Pre 4.0

Introduced

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_ATTDELETE
=============

The CDF_ATTDELETE procedure deletes an attribute from the specified CDF file. 
Note that the attribute’s entries are also deleted, and that the attributes 
that numerically follow the deleted attribute within the CDF file are 
automatically renumbered.

Examples

cid = CDF_CREATE('DEMOattdelete')

attr1_id = CDF_ATTCREATE(cid, 'GLOBAL_ATTR1', /GLOBAL_SCOPE)

attr2_id = CDF_ATTCREATE(cid, 'GLOBAL_ATTR2', /GLOBAL_SCOPE)

attr3_id = CDF_ATTCREATE(cid, 'VAR_ATTR1', /VARIABLE_SCOPE)

attr4_id = CDF_ATTCREATE(cid, 'VAR_ATTR2', /VARIABLE_SCOPE)

 

; Check the number of attributes:

info = CDF_INQUIRE(cid)

HELP, info.natts

 

; Delete the first and third attributes:

CDF_ATTDELETE, cid, 'GLOBAL_ATTR1'

; The attribute numbers are zero-based and automatically

; renumbered

CDF_ATTDELETE, cid, 1

 

; Select the new first attribute:

CDF_ATTINQ, cid, 0, name, scope, MaxEntry, MaxZentry

HELP, name, scope

 

CDF_DELETE, cid

IDL Output

<Expression> LONG = 4

 

NAME STRING = 'GLOBAL_ATTR2'

SCOPE STRING = 'GLOBAL_SCOPE'

Syntax

CDF_ATTDELETE, Id, Attribute [, EntryNum] [, /ZVARIABLE]

Arguments

ID

The CDF ID of the file containing the Attribute to be deleted, returned from a 
previous call to CDF_OPEN or CDF_CREATE.

Attribute

A string containing the name or zero-based attribute number of the attribute 
to be deleted.

EntryNum

The entry number to delete. If EntryNum is not specified, the entire attribute 
is deleted. If the attribute is variable in scope, this is either the name or 
number of the variable the attribute is to be associated with. If the attribute 
is global in scope, this is the actual gEntry. It is the user’s responsibility 
to keep track of valid gEntry numbers. Normally, gEntry numbers will begin with 
0 or 1 and will increase up to MAXGENTRY (as reported in the GET_ATTR_INFO 
structure returned by CDF_CONTROL), but this is not required.

Keywords

ZVARIABLE

If EntryNum 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 EntryNum is an rVariable ID. Note: the 
attribute must have a scope of VARIABLE_SCOPE.

Version History

4.0.1b

Introduced

See Also

CDF_ATTCREATE, CDF_ATTGET, CDF_ATTEXISTS, CDF_ATTINQ, CDF_ATTPUT, CDF_ATTRENAME

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_ATTEXISTS
=============

The CDF_ATTEXISTS function determines whether a given attribute exists in the 
specified CDF file. Attributes may be specified by name or number.

Examples

Create a function to test an attribute’s existence and return a string:

FUNCTION exists, cdfid, attname_or_number

IF CDF_ATTEXISTS(cdfid, attname_or_number) THEN $

   RETURN,' Attribute Exists' ELSE $

   RETURN,' Attribute Does Not Exist'

END

 

; Create a CDF with 2 attributes:

cdfid = CDF_CREATE('DEMOattexists')

attr1_id = CDF_ATTCREATE(cdfid, 'GLOBAL_ATT' , /GLOBAL_SCOPE)

attr2_id = CDF_ATTCREATE(cdfid, 'VARIABLE_ATT', /VARIABLE_SCOPE)

 

; Check the existence of the two attributes, plus a third that

; does not exist:

PRINT, EXISTS(cdfid, attr1_id)

PRINT, EXISTS(cdfid, 1)

PRINT, EXISTS(cdfid, 'BAD ATTR')

 

CDF_DELETE, cdfid

IDL Output

Attribute Exists

Attribute Exists

Attribute Does Not Exist

Syntax

Result = CDF_ATTEXISTS( Id, Attribute [, EntryNum] [, /ZVARIABLE] )

Return Value

Returns TRUE (1) if the specified attribute exists or FALSE (0) if it does not 
exist

Arguments

Id

The CDF ID of the file containing the Attribute to be checked, returned from a 
previous call to CDF_OPEN or CDF_CREATE.

Attribute

A string containing the name or zero-based attribute number of the attribute 
to be checked.

EntryNum

The entry number to confirm. If EntryNum is not specified, the entire file is 
searched for the specified attribute. If the attribute is variable in scope, 
this is either the name or number of the variable the attribute is to be 
associated with. If the attribute is global in scope, this is the actual 
gEntry. It is the user’s responsibility to keep track of valid gEntry numbers. 
Normally gEntry numbers will begin with 0 or 1 and will increase up to 
MAXGENTRY (as reported in the GET_ATTR_INFO structure returned by CDF_CONTROL), 
but this is not required.

Keywords

ZVARIABLE

If EntryNum 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 EntryNum is an rVariable ID. 
Note: the attribute must have a scope of VARIABLE_SCOPE.

Version History

4.0.1b

Introduced

See Also

CDF_ATTCREATE, CDF_ATTGET, CDF_ATTDELETE, CDF_ATTINQ, CDF_ATTPUT, CDF_ATTRENAME

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_ATTGET_ENTRY
================

The CDF_ATTGET_ENTRY procedure reads a variable attribute entry from a CDF file.

Examples

id = CDF_OPEN('test.cdf')

inq = CDF_INQUIRE(id)

 

; Read all the variable attribute entries.

 

; Walk through all of the zVariables

FOR varNum = 0, inq.nzvars-1 DO BEGIN

 

; Walk through all of the ZVariable attributes

   FOR attrNum = 0, inq.natts-1 DO BEGIN

 

      ; Read the variable attribute

      CDF_ATTGET_ENTRY, id, attrNum, varNum, attType, value, $

         status, /ZVARIABLE, CDF_TYPE=cdfType, $

         ATTRIBUTE_NAME=attName

      IF STATUS NE 1 THEN CONTINUE

      PRINT, "attr_name = ", attName, ", ", cdfType, ", ", $

         value

   ENDFOR

ENDFOR

Syntax

CDF_ATTGET_ENTRY, Id, Attribute, EntryNum, AttributeEntryType, Value, Status $ 
                  [, CDF_TYPE=variable] [, ATTRIBUTE_NAME=string] [, /ZVARIABLE]

Arguments

Id

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

Attribute

A string containing the name of the attribute or the attribute number to be 
written.

EntryNum

The entry number. If the attribute is variable in scope, this is either the 
name or number of the variable the attribute is to be associated with. If the 
attribute is global in scope, this is the actual gEntry. It is the user's 
responsibility to keep track of valid gEntry numbers. Normally, gEntry numbers 
begin with 0 or 1 and increase to MAXGENTRY (as reported in the GET_ATTR_INFO 
structure returned by CDF_CONTROL), but this is not required.

AttributeEntryType

The data type of the requested attribute entry.

Value

A named variable that will contain the attribute value.

Status

The procedure return status. A value of 1 is returned if the requested 
attribute exists and its entry is retrieved. Otherwise, 0 is returned.

Keywords

CDF_TYPE

Set this keyword to a named variable that will contain the CDF type of the 
attribute entry, returned as a scalar string. The possible string values are:

CDF_CHAR

CDF_UCHAR

CDF_INT1

CDF_BYTE

CDF_UINT1

CDF_UINT2

CDF_INT2

CDF_UINT4

CDF_INT4

CDF_INT8

CDF_REAL4

CDF_FLOAT

CDF_REAL8

CDF_DOUBLE

CDF_EPOCH

CDF_EPOCH16

CDF_TIME_TT2000

If the type cannot be determined, “UNKNOWN” is returned.

ATTRIBUTE_NAME

Set this keyword to a named variable that will hold the name of the requested 
attribute number.

ZVARIABLE

If EntryNum 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 behavior is to assume that EntryNum is an rVariable ID.

Note: The attribute must have a scope of VARIABLE_SCOPE.

Version History

 

8.0

Introduced

See Also

CDF_ATTGET

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_ATTGET
==========

The CDF_ATTGET procedure reads an attribute entry from a CDF file.

Examples

; Open the CDF file created in the CDF_ATTPUT example:

id = CDF_OPEN('foo')

CDF_ATTGET, id, 'Attribute2', 'Var2', x

PRINT, X, FORMAT='("[",9(X,F3.1,","),X,F3.1,"]")'

CDF_CLOSE, id ; Close the CDF file.

IDL Output

[ 0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0]

This is the expected output, since this attribute was created with a call to 
FINDGEN.

Syntax

CDF_ATTGET, Id, Attribute, EntryNum, Value [, CDF_TYPE= variable] [, /ZVARIABLE]

Arguments

Id

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

Attribute

A string containing the name of the attribute or the attribute number to be 
written.

EntryNum

The entry number. If the attribute is variable in scope, this is either the 
name or number of the variable the attribute is to be associated with. If the 
attribute is global in scope, this is the actual gEntry. It is the user’s 
responsibility to keep track of valid gEntry numbers. Normally, gEntry numbers 
will begin with 0 or 1 and will increase up to MAXGENTRY (as reported in the 
GET_ATTR_INFO structure returned by CDF_CONTROL), but this is not required.

Value

A named variable in which the value of the attribute is returned.

Keywords

CDF_TYPE

Set this keyword equal to a named variable that will contain the CDF type of 
the attribute entry, returned as a scalar string. Possible returned values 
are: CDF_CHAR, CDF_UCHAR, CDF_INT1, CDF_BYTE, CDF_UINT1, CDF_UINT2, CDF_INT2, 
CDF_UINT4, CDF_INT4, CDF_INT8, CDF_REAL4, CDF_FLOAT, CDF_REAL8, CDF_DOUBLE, 
CDF_EPOCH, CDF_EPOCH16, or CDF_TIME_TT2000. If the type cannot be determined, 
“UNKNOWN” is returned.

ZVARIABLE

If EntryNum 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 EntryNum is an rVariable ID.

Note: The attribute must have a scope of VARIABLE_SCOPE.

Version History

Pre 4.0

Introduced

6.3

Add support for EPOCH_16 type

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_ATTINQ
==========

The CDF_ATTINQ procedure obtains information about a specified attribute in a 
Common Data Format file.

Examples

cdfid= CDF_OPEN('/cdrom/ozone.8.20.92')

CDF_ATTINQ, cdfid, 0, name, scope, maxentry, maxzentry

PRINT, name, scope, maxentry, maxzentry

Syntax

CDF_ATTINQ, Id, Attribute, Name, Scope, MaxEntry [, MaxZEntry]

Arguments

Id

The CDF ID of the file containing the desired attribute, returned from a 
previous call to CDF_OPEN or CDF_CREATE.

Attribute

A string containing either the name or number of the attribute to be inquired.

Name

A named variable in which the name of the attribute is returned.

Scope

A named variable in which a string, describing the scope of the attribute, is 
returned. This string will have one of the following values: “GLOBAL_SCOPE”, 
“VARIABLE_SCOPE”, “GLOBAL_SCOPE_ASSUMED”, or “VARIABLE_SCOPE_ASSUMED”.

MaxEntry

A named variable in which the maximum rVariable entry number for this attribute 
is returned.

MaxZEntry

A named variable in which the maximum zVariable entry number for this attribute 
is returned.

Keywords

None

Version History

Pre 4.0

Introduced

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_ATTNUM
==========

The CDF_ATTNUM function returns the attribute number associated with a 
particular attribute in a Common Data Format file.

Examples

See the example for CDF_ATTPUT.

Syntax

Result = CDF_ATTNUM(Id, Attribute_Name)

Return Value

Returns the attribute number.

Arguments

Id

The CDF ID for the file that contains the desired attribute, returned from a 
previous call to CDF_OPEN or CDF_CREATE.

Attribute_Name

A string containing the name of the attribute.

Keywords

None

Version History

Pre 4.0

Introduced

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_ATTPUT
==========

The CDF_ATTPUT procedure writes an attribute entry to a Common Data Format file, 
or attaches an attribute to a CDF variable. If the specified entry already 
exists, it is overwritten.

Examples

Example 1

Id= CDF_CREATE('foo', /SUN_ENCODING, /HOST_DECODING, $

   /ROW_MAJOR)   ; no dimensions.

dummy= CDF_VARCREATE(id, 'Var1', /CDF_INT4, /REC_VARY)

v2= CDF_VARCREATE(id, 'Var2', /CDF_FLOAT, /REC_NOVARY)

dummy= CDF_ATTCREATE(id, 'Title', /VARIABLE)

global_dummy = CDF_ATTCREATE(id,'Date',/GLOBAL)

dummy= CDF_ATTCREATE(id, 'Att2', /VARIABLE)

CDF_ATTPUT, id, 'Title', 'Var1', 'Temperature at surface'

CDF_ATTPUT, id, 'Title', v2, 'Time of recording'

CDF_ATTPUT, id, 'Date',1,'July 4, 1996'

CDF_ATTPUT, id, 'Att2', 'Var2', FINDGEN(10)

 

; Rename the "Att2" attribute to "Attribute2":

CDF_ATTRENAME, Id, 'Att2', 'Attribute2'

 

; Verify the attribute number (zero-based) of Attribute2

PRINT, CDF_ATTNUM(id, 'Attribute2')

 

; Close the CDF file. This file is used in the CDF_ATTGET example.

CDF_CLOSE, id   

IDL Output

See Additional Examples for more on using CDF_ATTPUT.

Syntax

CDF_ATTPUT, Id, Attribute, EntryNum, Value [, /CDF_EPOCH | /CDF_DATATYPE*]
                                           [, /ZVARIABLE]

Arguments

Id

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

Attribute

A string containing either the name or number of the attribute to be written.

EntryNum

The entry number. If the attribute is variable in scope, this is either the 
name or number of the variable the attribute is to be associated with. If the 
attribute is global in scope, this is the actual gEntry. It is the user’s 
responsibility to keep track of valid gEntry numbers. Normally gEntry numbers 
will begin with 0 or 1 and will increase up to MAXGENTRY (as reported in the 
GET_ATTR_INFO structure returned by CDF_CONTROL), but this is not required.
The EntryNum for the variable-scoped attribute must point to an existing 
variable. 

Value

The value(s) to be written.

Keywords

CDF_EPOCH

This keyword sets Value (of IDL's double type) to type CDF_EPOCH in the 
CDF file. If this keyword is not set, Value is set to type CDF_DOUBLE.

Note: If the CDF_EPOCH keyword is set and the passed value is of IDL's int64 type, it is 
written as CDF_TIME_TT2000 data type. Without this keyword, the int64 
value is written as CDF_INT8 data type.

CDF_DATATYPE*

This is a defined value indicated what the actual CDF data type the entry is
written to. The defined value is one of the following: CDF_BYTE, CDF_CHAR, 
CDF_DOUBLE, CDF_EPOCH, CDF_FLOAT, CDF_INT1, CDF_INT2, CDF_INT4, CDF_INT8,
CDF_LONG_EPOCH, CDF_REAL4, CDF_REAL8, CDF_TIME_TT2000, CDF_UCHAR, CDF_UINT1,
CDF_UINT2, CDF_UINT4. To use this form, the entry Value has to have the 
matching IDL data type. Otherwise a mis-matched error could occur. This is 
a more specific way to write out the entry of the intended type to
avoid the potential type mistake. The aforementioned CDF_EPOCH will still
work, as specified.

ZVARIABLE

If EntryNum 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 EntryNum is an rVariable ID. 
Note: the attribute must have a scope of VARIABLE_SCOPE.

Additional Examples

Example 2

The following example uses the Global attribute “MODS” to keep track of the 
modification history of a CDF file named mods.cdf.

id = CDF_CREATE('mods.cdf', /CLOBBER)

cid = CDF_ATTCREATE(id, 'MODS', /GLOBAL_SCOPE)

CDF_ATTPUT, id, cid, 0, 'Original Version'

CDF_CLOSE, id

 

; Next, reopen the CDF file and make modifications:

id = CDF_OPEN('mods.cdf')

CDF_CONTROL, id, ATTRIBUTE='MODS', GET_ATTR_INFO=ginfo

 

;Use CDF_CONTROL to get the MAXGENTRY used.

CDF_ATTPUT, id, cid, ginfo.maxgentry+1,'Second Version'

 

;Insert the new gEntry at MAXGENTRY+1.

CDF_CLOSE, id

 

; Reopen the CDF file again and make more modifications:

id = CDF_OPEN('mods.cdf')

CDF_CONTROL, id, ATTRIBUTE='MODS', GET_ATTR_INFO=ginfo

CDF_ATTPUT, id, cid, ginfo.maxgentry+1, 'Third Version'

CDF_CLOSE, id

 

;Reopen the CDF file again and make a modification in the

;MAXGENTRY + 2 spot (skipping an entry number).

id = CDF_OPEN('mods.cdf')

CDF_CONTROL, id, ATTRIBUTE='MODS', GET_ATTR_INFO=ginfo

CDF_ATTPUT, id, cid, ginfo.maxgentry+2, 'Fourth Version'

 

; Now, examine the CDF file to review its modification history.

; Since the gENTRY numbers have a gap in them, we can check each

; attribute with the CDF_ATTEXISTS function. This is a good idea

; if you do not know for certain that the attribute entries are

; serially numbered.

 

CDF_CONTROL, id, ATTRIBUTE='MODS', GET_ATTR_INFO=ginfo

  FOR I=0, ginfo.maxgentry DO BEGIN

   IF CDF_ATTEXISTS(id, cid, I) THEN BEGIN

     CDF_ATTGET, id, cid, I, gatt

     PRINT, I, gatt, FORMAT='("Attribute: MODS (gENTRY #",i1,") = ",A)'

   ENDIF ELSE BEGIN

     PRINT, I, FORMAT='("Attribute: MODS (gENTRY #",i1,") $

       Does not exist")'

   ENDELSE

  ENDFOR

CDF_CLOSE, id

IDL Output

Attribute: MODS (gENTRY #0) = Original Version

Attribute: MODS (gENTRY #1) = Second Version

Attribute: MODS (gENTRY #2) = Third Version

Attribute: MODS (gENTRY #3) Does not exist

Attribute: MODS (gENTRY #4) = Fourth Version

Version History

Pre 4.0

Introduced

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_ATTRENAME
=============

The CDF_ATTRENAME procedure is used to rename an existing attribute in a 
Common Data Format file.

Examples

See the example for CDF_ATTPUT.

Syntax

CDF_ATTRENAME, Id, OldAttr, NewName

Arguments

Id

The CDF ID of the file containing the desired attribute, returned from a 
previous call to CDF_OPEN or CDF_CREATE.

OldAttr

A string containing the current name of the attribute or the attribute number 
to be renamed.

NewName

A string containing the new name for the attribute.

Keywords

None

Version History

Pre 4.0

Introduced

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_CLOSE
=========

The CDF_CLOSE procedure closes the specified Common Data Format file. The CDF’s 
data buffers are flushed, all of the CDF’s open files are closed, and the CDF 
identifier is freed. You must use CDF_CLOSE to close a CDF file to guarantee 
that all modifications you have made are actually written to disk.

Examples

; Open a file:

id = CDF_OPEN('open_close.cdf'

; ... Other CDF_ commands go here.

; Close the cdf file.

CDF_CLOSE, id

Syntax

CDF_CLOSE, Id

Arguments

Id

The CDF ID of the file to be closed, returned from a previous call to CDF_OPEN 
or CDF_CREATE.

Keywords

None

Version History

Pre 4.0

Introduced

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_COMPRESSION
===============

The CDF_COMPRESSION procedure sets or returns the compression mode for a CDF 
file and/or variables. Compression parameters should be set before values are 
written to the CDF file.

Special Note About Temporary File Location

CDF creates temporary files whenever files/variables are compressed or 
uncompressed. By default, these files are created in the system designated 
temporary directory: "/tmp" for Unix-based, or defined directory by environment
variable "TMP" or "TEMP" for Windows or "SYS$SCRATCH" for VMS. 
Users can set the environment variable CDF_TMP (Unix or Windows) or
CDF$TMP (VMS) to set the temporary directory explicitly. If none is defined,
the current directory will be used, which was the default place for pre-3.6.1 CDF.

Examples

; Create a CDF file and define the compression.

; Compression only works on Single-File CDFs:

id=CDF_CREATE('demo.cdf',[10,20],/CLOBBER,/SINGLE_FILE)

CDF_COMPRESSION,id,SET_COMPRESSION=1 ; (Run-length encoding)

att_id=CDF_ATTCREATE(id, 'Date',/GLOBAL)

CDF_ATTPUT,id,'Date',att_id,systime()

 

; Change the compression type for the file to GZIP by using

; SET_GZIP_LEVEL:

CDF_COMPRESSION,id,SET_GZIP_LEVEL=7

 

; Retrieve compression information:

CDF_COMPRESSION,id,GET_GZIP_LEVEL=glevel,GET_COMPRESSION=gcomp

HELP,glevel,gcomp

 

; Create and compress an rVariable:

rid=CDF_VARCREATE(id,'rvar0',[1,1],/CDF_FLOAT)

CDF_COMPRESSION,id,SET_VAR_COMPRESSION=2,VARIABLE='rvar0'

CDF_VARPUT,id,'rvar0',findgen(10,20,5)

CDF_COMPRESSION,id,GET_VAR_COMPRESSION=v_comp,VARIABLE=rid,$
   GET_VAR_GZIP_LEVEL=v_glevel

HELP,v_comp,v_glevel

 

; Create and compress a zVariable:

zid=CDF_varcreate(id,'zvar0',[1,1,1],DIM=[10,20,30],/ZVARIABLE,$

   /CDF_DOUBLE)

 

; You can set a compression and check it in the same call:

CDF_COMPRESSION,id,SET_VAR_GZIP_LEVEL=9,VARIABLE=zid,/ZVARIABLE,$

   GET_VAR_GZIP_LEVEL=v_gzip

HELP,v_gzip

 

CDF_VARPUT,id,zid,dindgen(10,20,30),/ZVARIABLE

 

; File and variable keywords can be combined in the same call

; (Set calls are processed before Get calls)

CDF_COMPRESSION,id,GET_VAR_COMPRESSION=v_comp,VARIABLE='zvar0',$

   /ZVARIABLE, SET_COMPRESSION=2,GET_COMPRESSION=file_comp

HELP,file_comp,v_comp

 

CDF_DELETE,id

IDL Output

GLEVEL LONG = 7

GCOMP LONG = 5

 

V_COMP LONG = 2

V_GLEVEL LONG = 0

 

(Note that V_GLEVEL is 0, since the variable compression is not GZIP.)

V_GZIP LONG = 9

 

FILE_COMP LONG = 2

V_COMP LONG = 5

Syntax

CDF_COMPRESSION, Id [, GET_COMPRESSION=variable] [, GET_GZIP_LEVEL=variable] $
                    [, GET_VAR_BLOCKINGFACTOR=variable] $
                    [, GET_VAR_COMPRESSION=variable] $
                    [, GET_VAR_GZIP_LEVEL=variable] $
                    [, SET_COMPRESSION={0 | 1 | 2 | 3 | 5}] $
                    [, SET_GZIP_LEVEL=integer{1 to 9}] $
                    [, SET_VAR_BLOCKINGFACTOR=value] $
                    [, SET_VAR_COMPRESSION={0 | 1 | 2 | 3 | 5}] $
                    [, SET_VAR_GZIP_LEVEL=integer{1 to 9}] $
                    [, VARIABLE=variable name or index] [, /ZVARIABLE]

Arguments

Id

The CDF ID of the file being compressed or queried, as returned from a 
previous call to CDF_OPEN or CDF_CREATE. Note that CDF compression only works 
for single-file CDF files (see CDF_CREATE).

Keywords

GET_COMPRESSION

Set this keyword to a named variable to retrieve the compression type used for 
the single-file CDF file. Note that individual CDF variables may compression 
types different that the one for the rest of the CDF file.

GET_GZIP_LEVEL

Set this keyword to a named variable in which the current GZIP effort level 
(1-9) for the CDF file is returned. If the compression type for the file is 
not GZIP (5), then a value of zero is returned.

GET_VAR_BLOCKINGFACTOR

Set this keyword to a named variable to retrieve the variable's blocking
factor. The blocking factor (as the number of records) defines the number
of continuous records placed in a block for a variable when the data is
written. A bigger blocking factor normally could provide a better performance
while reading/writing the data.

GET_VAR_COMPRESSION

Set this keyword to a named variable to retrieve the compression type for the 
variable identified by the VARIABLE keyword.

GET_VAR_GZIP_LEVEL

Set this keyword to a named variable in which the GZIP effort level (1-9) for 
variable specified by the VARIABLE keyword is returned. If the compression 
type for the variable is not GZIP (5), then a value of zero is returned.

SET_COMPRESSION

Set this keyword to the compression type to be used for the single-file CDF 
file. Note that individual CDF variables may use compression types different 
than the one for the rest of the CDF file. Valid compression types are:

0 = No Compression
1 = Run-Length Encoding
2 = Huffman
3 = Adaptive Huffman
5 = GZIP (see the optional GZIP_LEVEL keyword)
SET_GZIP_LEVEL

This keyword is used to indicate the desired effort for the GZIP compression. 
This effort must be expressed as a scalar in the range (1-9). If GZIP_LEVEL 
is not specified upon entry then the default effort level is taken to be 5. 
If the SET_GZIP_LEVEL keyword is set to a valid value, and the keyword 
SET_COMPRESSION is not specified, the SET_COMPRESSION is set to GZIP (5).

SET_VAR_BLOCKINGFACTOR

Set this keyword to a value, which represents the variable's blocking 
factor. The blocking factor (as the number of records) defines the number
of continuous records placed in a block for a variable when the data is
written. A bigger blocking factor normally could provide a better performance
while reading/writing the data.

SET_VAR_COMPRESSION

Set this keyword to the compression type for the variable identified by the 
VARIABLE keyword. If the variable is a zVariable, and is referred to by index 
in the VARIABLE keyword, then the keyword ZVARIABLE must be set. The desired 
variable compression should be set before variable data is added with 
CDF_VARPUT. Valid compression types are:

0 = No Compression
1 = Run-Length Encoding
2 = Huffman
3 = Adaptive Huffman
5 = GZIP (see the optional GZIP_LEVEL keyword)
SET_VAR_GZIP_LEVEL

Set this keyword to the GZIP effort level (1-9). If the compression type for 
the variable is not GZIP (5), no action is performed.

VARIABLE

Set this keyword to the name of a variable or a variable index to set the 
current variable. This keyword is mandatory when queering/setting the 
compression parameters of a rVariable or zVariable. 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 if the current variable is a zVARIABLE and is referred to by 
index 
in the VARIABLE keyword. For example:

CDF_COMPRESSION, id, VARIABLE=0, /ZVARIABLE,$
    GET_VAR_COMPRESSION=vComp

Version History

5.3

Introduced

See Also

CDF_CONTROL, CDF_CREATE, CDF_OPEN, CDF_VARNUM

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation.  All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_CONTROL
===========

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_LEAPSEONDLASTUPDATED=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_LEAPSEONDLASTUPDATED=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_LEAPSEONDLASTUPDATED

Set this keyword to a named variable in which to return the leap second 
last-updated date, in YYYYMMDD form, e.g., 20150701, as a 32-bit integer. This 
infomation 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_LEAPSEONDLASTUPDATED

Set this keyword to a 32-bit integer containing the leap second last-updated 
date, in the form YYYYMMDD, e.g., 20150701. This infomation 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_LEAPSEONDLASTUPDATED , GET_SPARSERECORDS, 
              SET_LEAPSEONDLASTUPDATED, GET_SPARSERECORDS keywords

See Also

CDF_CREATE, CDF_INQUIRE

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_CREATE
==========

The CDF_CREATE function creates a new Common Data Format file with the given 
filename and dimensions.

Note that when you create a CDF file, you may specify both encoding and 
decoding methods. Encoding specifies the method used to write data to the CDF 
file. Decoding specifies the method used to retrieve data from the CDF file 
and pass it to an application (IDL, for example). Encoding and decoding 
methods are specified by setting the XXX_ENCODING and XXX_DECODING keywords to 
CDF_CREATE. If no decoding method is specified, the decoding method is set to 
be the same as the encoding method.

All CDF encodings and decodings can be written or read on all platforms, but 
matching the encoding with the architecture used provides the best 
performance. Since most people work in a single-platform environment most of 
the time, the HOST_ENCODING method is used as the default encoding scheme. 
This provides maximum performance. If you know that the CDF file will be 
transported to a computer using another architecture, specify the encoding for 
the target architecture or specify IBMPC_ENCODING. Specifying the target 
architecture provides maximum performance on that architecture; specifying 
IBMPC_ENCODING provides the best encoding as most computers nowadays are 
Intel/AMD-based.

For more discussion on CDF encoding/decoding methods and combinations, see 
“Encoding” and “Decoding” in the CDF User’s Guide.

Note: Versions of IDL beginning with 6.3 support the CDF 3.1 library. If you 
need to create CDF files that can be read by earlier versions of IDL, or by 
CDF libraries earlier than version 3.0, use the 
CDF_SET_CDF27_BACKWARD_COMPATIBLE routine.

Examples

Use the following command to create a 10-element by 20-element CDF using 
network encoding and Sun decoding:

id = CDF_CREATE('cdf_create.cdf', [10,20], /NETWORK_ENCODING, $

   /SUN_DECODING)

; ... other cdf commands ...

CDF_CLOSE, id ; close the file.

Now suppose that we decide to use HP_DECODING instead. We can use the CLOBBER 
keyword to delete the existing file when creating the new file:

id = CDF_CREATE('cdf_create.cdf', [10,20], /NETWORK_ENCODING, $

   /HP_DECODING, /CLOBBER)

; ... other cdf commands ...

CDF_CLOSE, id ; close the file.

The new file is written over the existing file. Use the following command to 
delete the file:

CDF_DELETE, id

Syntax

Result = CDF_CREATE( Filename, [Dimensions] [, /CLOBBER] $
                               [, /MULTI_FILE | , /SINGLE_FILE] $
                               [, /COL_MAJOR | , /ROW_MAJOR] )

Encoding Keywords (pick one): 
[, /ALPHAOSF1_ENCODING]
[, /ALPHAVMSD_ENCODING]
[, /ALPHAVMSG_ENCODING]
[, /DECSTATION_ENCODING]
[, /HOST_ENCODING]
[, /HP_ENCODING]
[, /IBMPC_ENCODING]
[, /IBMRS_ENCODING]
[, /MAC_ENCODING]
[, /NETWORK_ENCODING] 
[, /NEXT_ENCODING]
[, /SGI_ENCODING]
[, /SUN_ENCODING]
[, /ARM_LITTLE_ENCODING]
[, /ARM_BIG_ENCODING]
[, /IA64VMSi_ENCODING]
[, /IA64VMSd_ENCODING]
[, /IA64VMSg_ENCODING]

Decoding Keywords (pick one): 
[, /ALPHAOSF1_DECODING]
[, /ALPHAVMSD_DECODING]
[, /ALPHAVMSG_DECODING]
[, /DECSTATION_DECODING] 
[, /HOST_DECODING] 
[, /HP_DECODING] 
[, /IBMPC_DECODING] 
[, /IBMRS_DECODING] 
[, /MAC_DECODING] 
[, /NETWORK_DECODING] 
[, /NEXT_DECODING]
[, /SGI_DECODING] 
[, /SUN_DECODING]
[, /ARM_LITTLE_DECODING]
[, /ARM_BIG_DECODING]
[, /IA64VMSi_DECODING]
[, /IA64VMSd_DECODING]
[, /IA64VMSg_DECODING]

Return Value

Returns the CDF ID for the new file.

Arguments

Filename

A scalar string containing the name of the file to be created. Note that if 
the desired filename has a .cdf ending, you can omit the extension and specify 
just the first part of the filename. For example, specifying “mydata” would 
open the file mydata.cdf.

Dimensions

A vector of values specifying size of each rVariable dimension. If no 
dimensions are specified, the file will contain a single scalar per record 
(i.e., a 0-dimensional CDF). This argument has no effect on zVariables.

Keywords

CLOBBER

Set this keyword to erase the existing file (if the file already exists) 
before creating the new version.

Note that if the existing file has been corrupted, the CLOBBER operation may 
fail, causing IDL to display an error message. In this case you must manually 
delete the existing file from outside IDL.

COL_MAJOR

Set this keyword to use column major (IDL-like) array ordering for variable 
storage.

MULTI_FILE

Set this keyword to cause all CDF control information and attribute entry data 
to be placed in one .cdf file, with a separate file created for each defined 
variable. If the variable is an rVariable, then the variable files will have 
extensions of .v0, .v1, etc.; zVariables will be stored in files with 
extensions of .z0, .z1, etc. See “Format” in the CDF User’s Guide for more 
information. If both SINGLE_FILE and MULTI_FILE are set the file will be 
created in the SINGLE_FILE format.

Note: In versions of IDL prior to 6.3, MULTI_FILE was the default.

MULTI_FILE Example:

id=CDF_CREATE('multi', /MULTI_FILE)

CDF_CONTROL, id, GET_FORMAT=cdf_format

HELP, cdf_format

IDL prints:

CDF_FORMAT STRING = 'MULTI_FILE'

ROW_MAJOR

Set this keyword to specify row major (C-like) array ordering for variable 
storage. This is the default.

SINGLE_FILE

Set this keyword to cause all CDF information (control information, attribute 
entry data, variable data, etc.) to be written to a single .cdf file. This is 
the default. See “Format” in the CDF User’s Guide for more information. If 
both SINGLE_FILE and MULTI_FILE are set the file will be created in the 
SINGLE_FILE format.

Note: In versions of IDL prior to 6.3, MULTI_FILE was the default.

Encoding Keywords

Select one of the following keywords to specify the type of encoding:

ALPHAOSF1_ENCODING

Set this keyword to indicate DEC ALPHA/OSF1 data encoding.

ALPHAVMSD_ENCODING

Set this keyword to indicate DEC ALPHA/VMS data encoding using Digital’s 
D_FLOAT representation.

ALPHAVMSG_ENCODING

Set this keyword to indicate DEC ALPHA/VMS data encoding using Digital’s 
G_FLOAT representation.

DECSTATION_ENCODING

Set this keyword to select Decstation (MIPSEL) data encoding.

HOST_ENCODING

Set this keyword to select that the file will use native data encoding. This 
is the default method.

HP_ENCODING

Set this keyword to select HP 9000 data encoding.

IBMPC_ENCODING

Set this keyword to select IBM PC data encoding.

IBMRS_ENCODING

Set this keyword to select IBM RS/6000 series data encoding.

MAC_ENCODING

Set this keyword to select Macintosh data encoding.

NETWORK_ENCODING

Set this keyword to select network-transportable data encoding (XDR).

NEXT_ENCODING

Set this keyword to select NeXT data encoding.

SGI_ENCODING

Set this keyword to select SGI (MIPSEB) data encoding (Silicon Graphics Iris 
and Power series).

SUN_ENCODING

Set this keyword to select SUN data encoding.

ARM_LITTLE_ENCODING

Set this keyword to select ARM little-endian data encoding.

ARM_BIG_ENCODING

Set this keyword to select ARM big-endian data encoding.

IA64VMSi_ENCODING

Set this keyword to indicate Itanium 64 on VMS data encoding using IEEE for
floating point representation.

IA64VMSd_ENCODING

Set this keyword to indicate Itanium 64 on VMS data encoding using Digital’s
D_FLOAT representation.

IA64VMSg_ENCODING

Set this keyword to indicate Itanium 64 on VMS data encoding using Digital’s
G_FLOAT representation.

Decoding Keywords

Select one of the following keywords to specify the type of decoding:

ALPHAOSF1_DECODING

Set this keyword to indicate DEC ALPHA/OSF1 data decoding.

ALPHAVMSD_DECODING

Set this keyword to indicate DEC ALPHA/VMS data decoding using Digital’s 
D_FLOAT representation.

ALPHAVMSG_DECODING

Set this keyword to indicate DEC ALPHA/VMS data decoding using Digital’s 
G_FLOAT representation.

DECSTATION_DECODING

Set this keyword to select Decstation (MIPSEL) data decoding.

HOST_DECODING

Set this keyword to select that the file will use native data decoding. This 
is the default method.

HP_DECODING

Set this keyword to select HP 9000 data decoding.

IBMPC_DECODING

Set this keyword to select IBM PC data decoding.

IBMRS_DECODING

Set this keyword to select IBM RS/6000 series data decoding.

MAC_DECODING

Set this keyword to select Macintosh data decoding.

NETWORK_DECODING

Set this keyword to select network-transportable data decoding (XDR).

NEXT_DECODING

Set this keyword to select NeXT data decoding.

SGI_DECODING

Set this keyword to select SGI (MIPSEB) data decoding (Silicon Graphics Iris 
and Power series).

SUN_DECODING

Set this keyword to select SUN data decoding.

ARM_LITTLE_DECODING

Set this keyword to select ARM little-endian data decoding.

ARM_BIG_DECODING

Set this keyword to select ARM big-endian data decoding.

IA64VMSi_DECODING

Set this keyword to indicate Itanium 64 on VMS data decoding using IEEE for
floating point representation.

IA64VMSd_DECODING

Set this keyword to indicate Itanium 64 on VMS data decoding using Digital’s
D_FLOAT representation.

IA64VMSg_DECODING

Set this keyword to indicate Itanium 64 on VMS data decoding using Digital’s
G_FLOAT representation.

Version History

Pre 4.0

Introduced

6.3

Changed default behavior to create a single file rather than multiple files 
(see SINGLE_FILE and MULTI_FILE)

Changed default behavior to use HOST_ENCODING rather than NETWORK_ENCODING

Changed default behavior to use HOST_DECODING rather than NETWORK_DECODING

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_DELETE
==========

The CDF_DELETE procedure deletes the specified Common Data Format file. Files 
deleted include the original .cdf file and the .v0, .v1, etc. files if they 
exist.

Examples

id = CDF_OPEN('open_close.cdf'); Open a file.

; ... other CDF_ commands ...

CDF_DELETE, id ; Close and Delete the cdf file.

Syntax

CDF_DELETE, Id

Arguments

Id

The CDF ID of the file to be deleted, returned from a previous call to 
CDF_OPEN or CDF_CREATE.

Keywords

None

Version History

Pre 4.0

Introduced

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_DOC
=======

The CDF_DOC procedure retrieves general documentation information about a 
Common Data Format file.

Examples

id=CDF_CREATE('VersionCheck')   ; Create a CDF file.

CDF_DOC, id, vers, rel, copy, INCREMENT=incr

PRINT,'File Written Using CDF', vers, rel, incr, $

   FORMAT='(A,I1,".",I1,"r",I2)'

CDF_CLOSE, id ; Close the CDF file.

IDL Output

File Written Using CDF2.6

Syntax

CDF_DOC, Id, Version, Release, Copyright [, INCREMENT=variable]

Arguments

Id

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

Version

A named variable in which the version number of the CDF library that created 
the CDF is returned.

Release

A named variable in which the release number of the CDF library that created 
the CDF is returned.

Copyright

A named variable in which the copyright notice of the CDF library that created 
the CDF is returned.

Keywords

INCREMENT

Set this keyword to a named variable that will contain the increment of the 
CDF library that created the specified CDF file.

Version History

Pre 4.0

Introduced

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_ENCODE_EPOCH16
==================

The CDF_ENCODE_EPOCH16 function encodes a CDF_EPOCH16 value into the standard 
date and time character string.

Examples

test_string = '04-Dec-2005 20:19:18.176.214.648.000'

test_epoch = CDF_PARSE_EPOCH16(test_string)

PRINT, CDF_ENCODE_EPOCH16(test_epoch)

IDL Output

04-Dec-2005 20:19:18.176.214.648.000

Syntax

Result = CDF_ENCODE_EPOCH16(Epoch16 [, EPOCH={0 | 1 | 2 | 3 | 4}] )

Note: Epoch16 field can be a single DCOMPLEX or an array of DCOMPLEX values.
      Based on the input, the output can be a single string or an array of 
      string.

Return Value

Returns the string representation of the given CDF_EPOCH16 value.

Arguments

Epoch16

The double-precision CDF_EPOCH16 value to be encoded.

Note: The CDF_EPOCH16 value can be obtained by calling CDF_EPOCH16 with the 
COMPUTE keyword, or by calling CDF_PARSE_EPOCH16.

Keywords

EPOCH

Set this keyword equal to one of the following integer values, specifying the 
epoch mode to use for output of the epoch date string:

Value

Date Format

0

DD-Mon-YYYY hh:mm:ss.ccc.uuu.nnn.ppp 
(This is the default)

1

YYYYMMDD.ttttttttttttttt

2

YYYYMMDDss

3

YYYY-MM-DDThh:mm:ss.ccc.uuu.nnn.pppZ
(The characters T and Z are the CDF_EPOCH16 type 3 place holders)

4

YYYY-MM-DDThh:mm:ss.ccc.uuu.nnn.ppp
(The characters T is the CDF_EPOCH16 type 3 place holder)

where:

Date Element

Represents

DD

the day of the month (1-31)

Mon

the abbreviated month name: (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, 
Nov, or Dec)

MM

the month number (1-12)

YYYY

the year (A.D.)

hh

the hour (0-23)

mm

the minute (0-59)

ss

the second (0-59)

ccc

the millisecond (0-999)

uuu

the microsecond (0-999)

nnn

the nanosecond (0-999)

ppp

the picosecond (0-999)

ttttttttttttttt

the fraction of the day (e.g. 500000000000000 is noon).

Version History

6.3

Introduced

See Also

CDF_EPOCH16, CDF_PARSE_EPOCH16

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_ENCODE_EPOCH
================

The CDF_ENCODE_EPOCH function encodes a CDF_EPOCH variable into a string. Four 
different string formats are available. The default (EPOCH=0) is the standard 
CDF format, which may be parsed by the CDF_PARSED_EPOCH function or broken 
down with the CDF_EPOCH procedure.

Examples

epoch_string = '04-Dec-1995 20:19:18.176'

epoch = CDF_PARSE_EPOCH(epoch_string)

HELP, epoch_string, epoch

 

; Create encode strings:

encode0 = CDF_ENCODE_EPOCH(epoch, EPOCH=0)

encode1 = CDF_ENCODE_EPOCH(epoch, EPOCH=1)

encode2 = CDF_ENCODE_EPOCH(epoch, EPOCH=2)

encode3 = CDF_ENCODE_EPOCH(epoch, EPOCH=3)

encode4 = CDF_ENCODE_EPOCH(epoch, EPOCH=4)

 

; Compare encoding formats:

HELP, encode0, encode1, encode2, encode3, encode4

IDL Output

EPOCH_STRING    STRING = '04-Dec-1995 20:19:18.176'

EPOCH           DOUBLE = 6.2985328e+13

 

ENCODE0         STRING = '04-Dec-1995 20:19:18.176'

ENCODE1         STRING = '19951204.8467381'

ENCODE2         STRING = '19951204201918'

ENCODE3         STRING = '1995-12-04T20:19:18.176Z'

ENCODE4         STRING = '1995-12-04T20:19:18.176'

Syntax

Result = CDF_ENCODE_EPOCH(Epoch [, EPOCH={0 | 1 | 2 | 3 | 4}] )

Return Value

Returns a string containing the encoded CDF_EPOCH variable.

Arguments

Epoch

The double-precision CDF_EPOCH value to be encoded. For more information about 
CDF_EPOCH values, see “Data Types” in the CDF User’s Guide.

Note: Epoch field can be a scalar or an array of epoch values. Based on the
      input, the output can be a single string or an array of string.

Keywords

EPOCH

Set this keyword equal to one of the following integer values, specifying the 
epoch mode to use for output of the epoch date string:

Value

Date Format

0

DD-Mon-YYYY hh:mm:ss.ccc 
(This is the default)

1

YYYYMMDD.ttttttt

2

YYYYMMDDhhmmss

3

YYYY-MM-DDThh:mm:ss.cccZ 
(The characters T and Z are the CDF_EPOCH type 3 place holders)

4

YYYY-MM-DDThh:mm:ss.ccc
(The character T is the CDF_EPOCH type 4 place holders)

where:

Date Element

Represents

DD
the day of the month (1-31)

Mon
the abbreviated month name: (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, 
Nov, or Dec)

MM
the month number (1-12)

YYYY
the year (A.D.)

hh
the hour (0-23)

mm
the minute (0-59)

ss
the second (0-59)

ccc
the millisecond (0-999)

ttttttt
the fraction of the day (e.g. 2500000 is 6 am).

Version History

4.0.1b

Introduced

See Also

CDF_EPOCH, CDF_PARSE_EPOCH

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_ENCODE_TT2000
=================

The CDF_ENCODE_TT2000 function encodes a single value or an array of 
CDF_TIME_TT2000 value(s) into the standard date and time character string(s). 
The default format of the string is ISO 8601 format:

yyyy-mm-ddThh:mm:ss.cccuuunnn

Examples

epoch_string = '2005-12-04T20:19:18.176321123'

epoch = CDF_PARSE_TT2000(epoch_string)

PRINT, CDF_ENCODE_TT2000(epoch)

 

CDF_TT2000, epoch2, 2005, 12, 4, 20, 19, 18, 176, 321, /compute

PRINT, CDF_ENCODE_TT2000(epoch2, epoch=0)

 

IDL Output

2005-12-04T20:19:18.176321123

04-Dec-2005 20:19:18.176321123

Syntax

Result = CDF_ENCODE_TT2000(Epoch [, EPOCH={0 | 1 | 2 | 3 | 4}] )

Note: Epoch field can be a scalar or an array of epoch values. Based on the
      input, the output can be a single string or an array of string.

Return Value

Returns a string containing the CDF_TIME_TT2000 values.

Arguments

Epoch

A scalar or an array (<=2D) of CDF_TIME_TT2000 values.

Keywords

EPOCH

Set this keyword equal to one of the following values, specifying the epoch 
mode to use for output of the epoch string:

Value

Date Format

0

DD-MM-YYYY hh:mm:ss.ccccccccc 
(This is the default)

1

YYYYMMDD.tttttttttt

2

YYYYMMDDss

3

YYYY-MM-DDThh:mm:ss.nnnnnnnnn
(T is a CDF_TIME_TT2000 type 3 place holder)

4

YYYY-MM-DDThh:mm:ss.nnnnnnnnnZ
(T and Z are CDF_TIME_TT2000 type 4 place holders)

where:

Date Element

Represents

DD
the day of the month (1-31)

MM
the month number (1-12)

YYYY
the year (A.D.)

hh
the hour (0-23)

mm
the minute (0-59)

ss
the second (0-59)

nnnnnnnnn
the millisecond (0-999), microsecond (000-999) and nanosecond (000-999)

ttttttt
the fraction of the day (e.g. 2500000 is 6 am).

Version History

3.4.0

Introduced

See Also

CDF_PARSE_TT2000, CDF_TT2000

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_EPOCH16
===========

The CDF_EPOCH16 procedure computes or breaks down a CDF_EPOCH16 value in a CDF 
file. When computing an epoch, any missing value is considered to be zero.

If you supply a value for the Epoch argument and set the BREAKDOWN_EPOCH 
keyword, CDF_EPOCH16 will compute the values of the Year, Month, Day, etc. and 
insert the values into the named variables you supply.

If you specify the Year (and optionally, the Month, Day, etc.) and set the 
COMPUTE_EPOCH keyword, CDF_EPOCH16 will compute the epoch and place the value 
in the named variable supplied as the Epoch parameter.

Note: You must set either the BREAKDOWN_EPOCH or COMPUTE_EPOCH keyword.
      The procedure allows input of an array of EPOCH16 values. Initially,
      it could only handle a single EPOCH16 value.


Examples

To compute the epoch value of September 20, 2005 at 3:05:46:02:156 am:

CDF_EPOCH16, epoch, 2005, 9, 20, 3, 5, 46, 27, 2, 156, $
   /COMPUTE_EPOCH

To break down the given epoch value into standard date components:

CDF_EPOCH16, epoch, yr, mo, dy, hr, min, sec, milli, micro, nano, pico, $
   /BREAKDOWN_EPOCH

Syntax

CDF_EPOCH16, Epoch, Year [, Month, Day, Hour, Minute, Second, Milli, Micro, $
                          Nano, Pico] [, /BREAKDOWN_EPOCH] [, /COMPUTE_EPOCH]

Note: To compute the epoch, the date/time componments can be either a single 
      value or an array of values. The output Epoch field can be a scalar or
      an array of values. To break down the epoch, the Epoch field can be a 
      scalar or an array of epoch values. Based on the input, the date/time 
      componments can be a single value each, or an array of values.

Arguments

Epoch

The Epoch value to be broken down, or a named variable that will contain the 
computed epoch will be placed. The Epoch value is the number of picoseconds 
since 01-Jan-0000 00:00:00.000.000.000.000.

Note: “Year zero” is a convention chosen by CDF to measure epoch values. This 
date is more commonly referred to as 1 BC. Remember that 1 BC was a leap year. 
The Epoch is defined as the number of picoseconds since 
01-Jan-0000 00:00:00.000.000.000.000, as computed using the CDF library’s 
internal date routines. The CDF date/time calculations do not take into 
account the changes to the Gregorian calendar, and cannot be directly converted 
into Julian date/times. To convert between CDF epochs and date/times, use the 
CDF_EPOCH16 routine with either the BREAKDOWN_EPOCH or CONVERT_EPOCH keywords.

Year

If COMPUTE_EPOCH is set, a four-digit integer representing the year.

If BREAKDOWN_EPOCH is set, a named variable that will contain the year.

Month

If COMPUTE_EPOCH is set, an integer between 1 and 12 representing the month. 
Alternately, you can set Month equal to zero, in which case the Day argument 
can take on any value between 1-366.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
month value.

Day

If COMPUTE_EPOCH is set, an integer between 1 and 31 representing the day of 
the month. Alternately, if the Month argument is set equal to zero, Day can be 
an integer between 1-366 representing the day of the year.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric day 
of the month value.

Hour

If COMPUTE_EPOCH is set, an integer between 0 and 23 representing the hour of 
the day.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric hour 
of the day value.

Minute

If COMPUTE_EPOCH is set, an integer between 0 and 59 representing the minute of 
the hour.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
minute of the hour value.

Second

If COMPUTE_EPOCH is set, an integer between 0 and 59 representing the second 
of the minute.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
second of the minute value.

Milli

If COMPUTE_EPOCH is set, an integer between 0 and 999 representing the 
millisecond.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
millisecond value.

Micro

If COMPUTE_EPOCH is set, an integer between 0 and 999 representing the 
microsecond.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
microsecond value.

Nano

If COMPUTE_EPOCH is set, an integer between 0 and 999 representing the 
nanosecond.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
nanosecond value.

Pico

If COMPUTE_EPOCH is set, an integer between 0 and 999 representing the 
picosecond.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
picosecond value.

Keywords

BREAKDOWN_EPOCH

Set this keyword to break down the value of the Epoch argument into its 
component parts, storing the resulting year, month, day, etc. values in the 
variables specified by the corresponding arguments.

COMPUTE_EPOCH

Set this keyword to compute the value of Epoch from the values specified by 
the Year, Month, Day, etc. arguments.

Version History

6.3

Introduced

 

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_EPOCH_COMPARE
=================

The CDF_EPOCH_COMPARE function compares two epoch (date and time) values.

Values can be scalars or an array of values. The epoch can be one of the CDF 
formats, CDF_EPOCH, CDF_EPOCH16 or CDF_TIME_TT2000. While data of type 
CDF_EPOCH and CDF_EPOCH16 can be compared with each other, data in 
CDF_TIME_TT2000 can be compared only with data of the same type.

If the base epoch is a scalar, it is used to compare with all values in the 
first epoch. If the base epoch is an array, the same element in the source and 
base epoch array is compared. If a third argument, endepoch, is provided, the 
baseepoch and endepoch are used as the starting and ending epoch that the 
source epoch will be checked against.

The procedure allows input of an array of values to compare. Initially, it
can only handle a scalar.


Examples

; For CDF_EPOCH data type

CDF_VARGET, id, "Epoch", ep, REC_COUNT=1000,/ZVARIABLE

CDF_EPOCH, base, 2005,6,1,10,18,17,2,/COMPUTE

ret= CDF_EPOCH_COMPARE(ep,base)

HELP, ret

 

; For CDF_TIME_TT2000 data type

CDF_VARGET, id2, "Epoch", ep2, REC_COUNT=1000,/ZVARIABLE

CDF_TT2000, base2, 2005,6,1,10,18,17,2,3,4,/COMPUTE

ret2= CDF_EPOCH_COMPARE(ep2,base2)

HELP, ret2

 

; For CDF_EPOCH data type

CDF_VARGET, id3, "Epoch", ep3, REC_COUNT=1000,/ZVARIABLE

CDF_EPOCH, starting, 2005,6,1,10,18,17,2,/COMPUTE

CDF_EPOCH, ending, 2005,6,10,10,18,17,2,/COMPUTE

ret3= CDF_EPOCH_COMPARE(ep3,starting,ending)

HELP, ret3

Syntax

Result = CDF_EPOCH_COMPARE(epoch, baseepoch, [endepoch])

Return Value

Using Two Arguments

If the function uses two arguments, the return value is a scalar value or an 
array of integer values (1, 0, or -1), depending on the source epoch.

If the value of the first epoch is greater (later date and time) than the base 
epoch, 1 is set.

If the value of the first epoch is the same as the base epoch, 0 is set.

If the value of the first epoch is less (earlier date and time) than the base 
epoch, -1 is set.

Result	Condition
1

if epoch1 > baseepoch

0

if epoch1 = baseepoch

-1

if epoch1 < baseepoch

Using Three Arguments

If the function uses three arguments, the return value is a scalar value or an 
array of integer values (1 or 0).

If the value of the source epoch falls within the starting and ending epoch, 1 
is set. Otherwise, 0 is set.

1	if baseepoch <= epoch1 <= endepoch
0	Otherwise

Arguments

epoch

A single or an array of epoch value(s) returned from:

CDF_EPOCH,/compute, CDF_EPOCH16,/compute for CDF_EPOCH or CDF_EPOCH16 data type
CDF_TT2000,/compute for CDF_TIME_TT2000 data type
CDF_VARGET, or CDF_VARGET1

baseepoch

A single or an array of epoch value(s) returned from:

CDF_EPOCH,/compute, CDF_EPOCH16,/compute for CDF_EPOCH or CDF_EPOCH16 data type
CDF_TT2000,/compute for CDF_TIME_TT2000 data type
CDF_VARGET, or CDF_VARGET1

endepoch

A single or an array of epoch value(s) returned from:

CDF_EPOCH,/compute, CDF_EPOCH16,/compute for CDF_EPOCH or CDF_EPOCH16 data type
CDF_TT2000,/compute for CDF_TIME_TT2000 data type
CDF_VARGET, or CDF_VARGET1

Note: This field must be of the same data type and dimensionality as baseepoch.

Keywords

None

Version History

6.4

Introduced

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_EPOCH_DIFF
==============

The CDF_EPOCH_DIFF function compares two epoch (date and time) values and 
returns the difference in milliseconds (default) or microseconds.

The procedure allows input of an array of values to compare. Initially, it
could only handle a scalar.

Examples

CDF_EPOCH, epoch, 2005,6,1,10,18,17,2,/COMPUTE

CDF_EPOCH, epoch1, 2005,6,1,10,18,17,2,3,4,5,/COMPUTE

CDF_EPOCH, epoch2, 2005,6,1,10,18,17,2,1,4,5,/COMPUTE

CDF_EPOCH, epoch3, 2005,6,1,10,18,17,1,/COMPUTE

PRINT, 'Difference between epoch1 and epoch, in milliseconds: ',$

   CDF_EPOCH_DIFF(epoch1,epoch)

PRINT, 'Difference between epoch1 and epoch, in microseconds: ',$

   CDF_EPOCH_DIFF(epoch1,epoch,/MICRO_SECONDS)

PRINT, 'Difference between epoch1 and epoch2, in microseconds: ',$

   CDF_EPOCH_DIFF(epoch1,epoch2,/MICRO_SECONDS)

PRINT, 'Difference between epoch1 and epoch3, in microseconds: ',$

   CDF_EPOCH_DIFF(epoch1,epoch3,/MILLI_SECONDS)

Syntax

Result = CDF_EPOCH_DIFF(epoch1, epoch2 [, /MILLI_SECONDS] $
                                       [, /MICRO_SECONDS])

Arguments

epoch1
epoch2

An epoch value returned from CDF_EPOCH or CDF_EPOCH16 with the COMPUTE keyword 
set, or from CDF_VARGET or CDF_VARGET1.

Keywords

MILLI_SECONDS

Set this keyword to return the difference in milliseconds. This is the default.

MICRO_SECONDS

Set this keyword to return the difference in microseconds.

Version History

6.4

Introduced


© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_EPOCH_FROMJULDAYS
-------------------

The CDF_EPOCH_FROMJULDAYS function converts Julian day(s) to CDF epoch value(s),
in CDF_EPOCH, CDF_EPOCH16 or CDF_TIME_TT2000 data type. The input Julian data 
can be a single day or a vector of days, each day is a double, similar to
IDL's JULDAY returned object.  Optionally, the returned epochs can be in a
string(s) of ISO 8601 format.

Note
   You must set one of the EPOCH, LONGEPOCH or TT2000 keywords. 

Syntax 
   Result = CDF_EPOCH_FROMJULDAYS (julday, [,/EPOCH] [,/LONGEPOCH],
                                           [,/TT2000] [,/STRING]) 

Arguments 
   julday   An Julian value(s)


Keywords 
   EPOCH    The Epoch value is of CDF_EPOCH data type
   LONGEPOCH The Epoch value is of CDF_EPOCH16 data type
   TT2000   The Epoch value is of CDF_TIME_TT2000 data type
   
   STRING   Signal that the returned date(s) in ISO 8601 format string

Examples 
   cdf_epoch, epoch, 2020, 2, 3, 4, 5, 6, 777, /compute_epoch
   julday = cdf_epoch_tojuldays(epoch)
   epoch2 = cdf_epoch_fromjuldays (epoch, /epoch)
   str_epoch2 = cdf_epoch_fromjuldays (epoch, /epoch, /string)

Version History 
  Introduced:  CDF V3.8.0

See Also 
  CDF_EPOCH, CDF_EPOCH16, CDF_TT2000, CDF_EPOCH_TOJULDAYS

 
CDF_EPOCH_TOJULDAYS
===================

The CDF_EPOCH_TOJULDAYS function converts CDF epoch values in CDF_EPOCH, 
CDF_EPOCH16 or CDF_TIME_TT2000 data type to Julian days. This function is 
similar to the IDL JULDAY function.

Examples

CDF_VARGET, id, "Epoch", epoch, REC_COUNT=1000,/ZVARIABLE

ret = CDF_EPOCH_TOJULDAYS (epoch)

ret2 = CDF_EPOCH_TOJULDAYS (epoch, /string)

Syntax

Result = CDF_EPOCH_TOJULDAYS(EPOCH [, /STRING])

Arguments

Epoch

An epoch value returned from CDF_EPOCH /compute, CDF_EPOCH16, /compute, 
CDF_VARGET or CDF_VARGET1.

Keywords

STRING

Set this keyword to return the dates as a string in ISO 8601 format.

Version History

CDF 3.4.0

Introduced

See Also

CDF_EPOCH, CDF_EPOCH16, CDF_TT2000

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


=========

The CDF_EPOCH procedure computes or breaks down all CDF epoch values
of CDF_EPOCH, CDF_EPOCH16 or CDF_TIME_TT2000 (as TT2000) type, in a CDF 
file. When computing an epoch, any missing value is considered to be zero.

If you supply a value for the Epoch argument and set the BREAKDOWN_EPOCH 
keyword, CDF_EPOCH will compute the values of the Year, Month, Day, etc. and 
insert the values into the named variables you supply. If you specify the Year 
(and optionally, the Month, Day, etc.) and set the COMPUTE_EPOCH keyword, 
CDF_EPOCH will compute the epoch and place the value in the named variable 
supplied as the Epoch parameter.

Note: You must set either the BREAKDOWN_EPOCH or COMPUTE_EPOCH keyword. With 
      the COMPUTE_EPOCH keyword, the number of date/time components will
      determine which type the computed epoch value(s) will be: CDF_EPOCH 
      (a double) or CDF_EPOCH16 (an IDL double complex). If the number of 
      components is seven (7) or less, then the computed epoch will be of 
      CDF_EPOCH. If it is more than 7 with microseconds, etc, provided, then 
      the computed epoch will be of CDF_EPOCH16. The keyword TT2000 is used
      with COMPUTE_EPOCH, which will compute epoch value(s) of TT2000 type 
      (a 8-byte integer) that will allow nine (9) components, down to 
      nanoseconds. This procedure could handle a scalar or an array of values
      as input. 

Examples

To compute the epoch value of September 20, 1992 at 3:00 am into a CDF_EPOCH
value:

CDF_EPOCH, MergeDate, 1992, 9, 20, 3, /COMPUTE_EPOCH

To break down the given epoch value into standard date components:

CDF_EPOCH, 4.7107656e13, yr, mo, dy, hr, mn, sc, milli, /BREAK

To compute the epoch values of September 20, 2000 at 3:00 am and 4:00 am 
into a pair of TT2000 values:

CDF_EPOCH, times, [2000,2000], [9,9], [20,20], [3,4], /COMPUTE_EPOCH, /TT2000

To break down the previous computed epoch value into standard date/time
components. Each component will be an array with 2 values:

CDF_EPOCH, times, yr, mo, dy, hr, mn, sc, milli, micro, nano, /BREAK

This will compute the epoch value of year: 2020, month: 10, day: 20,
hour: 11, minute: 12, second: 13, millisecond: 333, microsecond: 444,
nanosecond: 555, picosecond: 666 into a CDF_EPOCH16 value:

CDF_EPOCH, epoch16, 2020, 10, 20, 11, 12, 13, 333, 444, 555, 666, /COMPUTE_EPOCH

Syntax

CDF_EPOCH, Epoch, Year [, Month, Day, Hour, Minute, Second, Milliseconds
                          [, Microseconds] [, Nanoseconds] [, Picoseconds]] $
                       [, /BREAKDOWN_EPOCH] [, /COMPUTE_EPOCH] [, /TT2000]

Note: To compute the epoch, the date/time components can be either a single
      value or an array of values (each date/time component having the same 
      number of elements in its array). The output Epoch field can be a scalar 
      or an array of values. To break down the epoch, the Epoch field can be a
      scalar or an array of epoch values. Based on the input, the date/time
      components can be a single value each, or an array of values.

Arguments

Epoch

The Epoch value to be broken down, or a named variable that will contain the 
computed epoch will be placed. The Epoch value(s) is CDF type dependent. It is
the number of milliseconds since 0000-01-01T00:00:00.000 for CDF_EPOCH, 
the number of picoseconds since 0000-01-01T00:00.000000000000 for CDF_EPOCH16,
or the number of nanoseconds since J2000 (with leap seconds included).

Note: “Year zero” is a convention chosen by NSSDC to measure epoch values. 
This date is more commonly referred to as 1 BC. Remember that 1 BC was a leap 
year. The Epoch is defined as the number of milliseconds since 
01-Jan-0000 00:00:00.000, as computed using the CDF library’s internal date 
routines. The CDF date/time calculations do not take into account the changes 
to the Gregorian calendar, and cannot be directly converted into Julian 
date/times. To convert between CDF epochs and date/times, use the CDF_EPOCH 
routine with the BREAKDOWN_EPOCH.

Year

If COMPUTE_EPOCH is set, a four-digit integer representing the year.

If BREAKDOWN_EPOCH is set, a named variable that will contain the year.

Month

If COMPUTE_EPOCH is set, an integer between 1 and 12 representing the month. 
Alternately, you can set Month equal to zero, in which case the Day argument 
can take on any value between 1-366.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
month value.

Day

If COMPUTE_EPOCH is set, an integer between 1 and 31 representing the day of 
the month. Alternately, if the Month argument is set equal to zero, Day can be 
an integer between 1-366 representing the day of the year.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric day 
of the month value.

Hour

If COMPUTE_EPOCH is set, an integer between 0 and 23 representing the hour of 
the day.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric hour 
of the day value.

Minute

If COMPUTE_EPOCH is set, an integer between 0 and 59 representing the minute 
of the hour.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
minute of the hour value.

Second

If COMPUTE_EPOCH is set, an integer between 0 and 59 representing the second 
of the minute.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
second of the minute value.

Milliseconds

If COMPUTE_EPOCH is set, an integer between 0 and 999 representing the 
millisecond. Alternately, if the Hour, Minute, and Second arguments are set 
all equal to zero, Milliseconds can be an integer between 0-86400000 
representing the milliseconds of the day. If this is the last component,
the computed epoch value(s) will be a CDF_EPOCH type or a TT2000 type if 
TT2000 keyword is also specified.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
millisecond value(s).  Note: For a CDF_EPOCH data type value(s), the 
last component, millisecond, will be an integer. Any 
sub-millisecond information will be lost. If users intend to have this portion,
you can retrieve it by doing some simple IDL statements as it is the fraction
portion of a double epoch value(s):

  micro = (value-floor(value,/l64)) * 1.e3
  nano = (micro-floor(micro,/l64)) * 1.e3

Just a caveat, the precision of micro, and mostly nano, can be off with the 
scaling.

Microseconds

If COMPUTE_EPOCH is set, an integer between 0 and 999 representing the 
microsecond. This component is used for CDF_EPOCH16 or TT2000 data type.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
microsecond value(s).

Nanoseconds

If COMPUTE_EPOCH is set, an integer between 0 and 999 representing the 
nanosecond. This component is used for CDF_EPOCH16 or TT2000 data type.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
nanosecond value(s).

Picoseconds

If COMPUTE_EPOCH is set, an integer between 0 and 999 representing the 
picoseconds. This is valid only for CDF_EPOCH16 data type.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
picosecond value(s).

Keywords

BREAKDOWN_EPOCH

Set this keyword to break down the value(s) of the Epoch argument into its 
component parts, storing the resulting year, month, day, etc. values in the 
variables specified by the corresponding arguments.

COMPUTE_EPOCH

Set this keyword to compute the value(s) of Epoch from the values specified by 
the Year, Month, Day, etc. arguments.

TT2000

Set this keyword to compute the TT2000 value(s) of Epoch from the values 
specified by the Year, Month, Day, etc. arguments.

Version History

Pre 4.0

Introduced

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_EPOCH_UNIXTIME
==================

The CDF_EPOCH_UNIXTIME function converts time(s) in CDF_EPOCH, CDF_EPOCH16 or
CDF_TIME_TT2000 (TT2000) to/from Unix time(s). The source time(s) can be a
scalar or array.

The CDF_EPOCH time is milliseconds from 0000-01-01 00:00:00.000 in idl double.
The CDF_EPOCH16 (long epoch) time is picoseconds from 0000-01-01 00:00:00.000 in
idl double complex. The TT2000 time in nanoseconds from J2000 with leap seconds
in idl long64. The unix time is seconds from 1970-01-01 00:00:00 in idl double. 
The Unix time can have sub-second, with a time resolution of microseconds, in
its fractional part.

Note: Since TT2000 and CDF_EPOCH16 has higher time resolution, the converted
      time might not preserve the full resolution for sub-microseconds. 
      CDF_EPOCH does not have the time resolution for microseconds. The
      conversion will not preserve it if the Unix time has that.

Examples

To convert the CDF_EPOCH times at 1969-12-31T23:59:59.000,
1970-01-01T00:00:00.000 and 1970-01-01T00:00:01.000 to their corresponding unix
times.

V3 = CDF_PARSE_EPOCH (['1969-12-31T23:59:59.000','1970-01-01T00:00:00.000',$
                       '1970-01-01T00:00:01.000'])
help, V3
V3              DOUBLE    = Array[3]
unixtimes = CDF_EPOCH_UNIXTIME (V3)
print, unixtimes
      -1.0000000       0.0000000       1.0000000

To convert unix times back to CDF_EPOCH:

E3 = CDF_EPOCH_UNIXTIME (unixtimes, /EPOCH)
print, CDF_ENCODE_EPOCH(E3)
1969-12-31T23:59:59.000 1970-01-01T00:00:00.000 1970-01-01T00:00:01.000

To convert the same unix times to TT2000:

T3 = CDF_EPOCH_UNIXTIME (unixtimes, /TT2000)
help, T3
T3              LONG64    = Array[3]
print, CDF_ENCODE_TT2000(T3)
1969-12-31T23:59:59.000000000 1970-01-01T00:00:00.000000000 
1970-01-01T00:00:01.000000000

To convert the same unix times to CDF_EPOCH16:

TT2000 = CDF_EPOCH_UNIXTIME (unixtimes, /LONGEPOCH)
help, TT2000
TT2000             DCOMPLEX  = Array[3]
print, CDF_ENCODE_TT2000(TT2000)
1969-12-31T23:59:59.000000000000 1970-01-01T00:00:00.000000000000
1970-01-01T00:00:01.000000000000

Syntax

Result = CDF_EPOCH_UNIXTIME (Time [, /EPOCH] [, /LONGEPOCH] $
                                  [, /TT2000])

Arguments

Time

The time, unix time or CDF based time, to be converted. It can be a scalar value
or an array of values. Without any keyword, it is converting a CDF based time(s)
to unix time(s). 

Keywords

EPOCH

Set this keyword to convert a unix time(s) to a CDF_EPOCH data type time(s).

LONGEPOCH

Set this keyword to convert a unix time(s) to a CDF_EPOCH16 data type time(s).

TT2000

Set this keyword to convert a unix time(s) to a CDF's TT2000 data type time(s).

Version History

Pre 4.0

Introduced

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_ERROR
=========

The CDF_ERROR function returns a a short explanation of a given status code 
returned from a Common Data Format file.

Syntax

Result = CDF_ERROR(Status)

Return Value

Returns a string containing a status code explanation.

Arguments

Status

The status code to be explained.

Keywords

None

Version History

Pre 4.0

Introduced

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_EXISTS
==========

The CDF_EXISTS function returns true if the Common Data Format (CDF) scientific 
data format library is supported on the current IDL platform.

This routine is written in the IDL language. Its source code can be found in 
the file cdf_exists.pro in the lib subdirectory of the IDL distribution.

Examples

The following IDL command prints an error message if the CDF library is not 
available:

IF CDF_EXISTS() EQ 0 THEN PRINT, 'CDF not supported.'

Syntax

Result = CDF_EXISTS( )

Return Value

Returns a 1 (True) if the library is supported or a 0 (False) if the library 
is not supported.

Arguments

None

Keywords

None

Version History

Pre 4.0

Introduced

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_INQUIRE
===========

The CDF_INQUIRE function returns global information about the Common Data 
Format file. The tags of this structure are described below.

Examples

cdfid = CDF_CREATE('CDFinquire', /HP_ENCODING, /MAC_DECODING)

attr1_id = CDF_ATTCREATE(cdfid, 'GLOBAL_ATT', /GLOBAL_SCOPE)

attr2_id = CDF_ATTCREATE(cdfid,'VARIABLE_ATT', /VARIABLE_SCOPE)

CDF_CONTROL, cdfid, GET_NUMATTRS = num_attrs

PRINT, 'This CDF has ', num_attrs(0), $

   'Global attribute(s) and ', num_attrs(1), $

   'Variable attribute(s).', $

   FORMAT='(A,I2,A,I2,A)'

 

inquire = CDF_INQUIRE(cdfid)

HELP, inquire, /STRUCT

CDF_DELETE, cdfid ; Delete the CDF file.

IDL Output

This CDF has 1 Global attribute(s) and 1 Variable attribute(s).

 

** Structure <4003e0c0>, 9 tags, length=48, refs=1:

   NDIMS 	LONG 0

   DECODING 	STRING  	'MAC_DECODING'

   ENCODING 	STRING    	'HP_ENCODING'

   MAJORITY 	STRING    	'ROW_MAJOR'

   MAXREC 	LONG 			-1

   NVARS 	LONG 			0

   NZVARS 	LONG 			0

   NATTS 	LONG 			2

   VERSION  	STRING    	'3.7.0'

   DIM 		LONG 		Array[1]

Syntax

Result = CDF_INQUIRE(Id)

Return Value

This information is returned in a structure of the form:

{ NDIMS:0L, DECODING:"", ENCODING:"", MAJORITY:"", MAXREC:0L, $

  NVARS:0L, NZVARS:0L, NATTS:0L, VERSION:"", DIM:LONARR(NDIMS) }

Explanation of the Structure Tags

The structure returned by this function consists of the following tags:

Tag

Description

NDIMS

The longword integer specifying the number of dimensions in the rVariables in 
the current CDF.

DECODING

A string describing the decoding type set in the CDF file, such as 
‘MAC_DECODING’ or ‘ALPHAVMSD_ENCODING’.

ENCODING

A string describing the type of encoding used in the CDF file, such as 
‘NETWORK_ENCODING’ or ‘SUN_ENCODING’.

MAJORITY

A string describing the majority used in the CDF file. The majority will be 
either row (‘ROW_MAJOR’) or column (‘COL_MAJOR’).

MAXREC

A longword integer specifying the highest record number written in the 
rVariables in the current CDF. The MAXREC field will contain the value -1 if 
no rVariables have yet been written to the CDF.

NVARS

A longword integer specifying the number of rVariables (regular variables) in 
the CDF.

NZVARS

A longword integer specifying the number of zVariables in the CDF.

NATTS

A longword integer specifying the number of attributes in the CDF. Note that 
the number returned in this field includes both global and variable attributes. 
You can use the GET_NUMATTR keyword to the CDF_CONTROL routine to determine 
the number of each.

VERSION

A string describing the CDF's version/release/increment.

DIM

A vector where each element contains the corresponding dimension size for the 
rVariables in the current CDF. For 0-dimensional CDF’s, this argument contains 
a single element (a zero).

Arguments

Id

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

Keywords

None

Version History

Pre 4.0

Introduced

See Also

CDF_CONTROL, CDF_DOC, CDF_LIB_INFO

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_LEAPSECONDS_INFO
====================

The CDF_LEAPSECONDS_INFO function returns a structure containing information 
about the leap seconds used by CDF.

Example

info = CDF_LEAPSECONDS_INFO()

help, info, /struct

print, info

Syntax

Result = CDF_LEAPSECONDS_INFO( )

Return Value

The returned structure has the form:

{ USE_FILE: 1, CDF_LEAPSECONDSTABLE:"...", $

LASTUPDATED:LONARR(...), LEAPSECONDS: DOUBLEARR(...)}

Structure Tag	Description
USE_FILE	
0 - The leap seconds are based on the hard-coded table in the CDF library, 
    which may not have the latest leap second(s) if the library is not 
    up-to-date.

1 - The leap seconds are read from a file.

CDF_LEAPSECONDSTABLE	
This field contains the value of the 
CDF_LEAPSECONDSTABLE environment variable, if it is defined. Its value should 
be the file name of the leap seconds table. Data contents for the leap seconds 
should be properly formatted to be valid for use.

LASTUPDATED	
This field is an array of integers that shows the last date, in year, month 
and day, that the leap seconds table is updated, which can show whether the 
table is up-to-date.

LEAPSECONDS	
This field contains the contents of the leap seconds table that is used by CDF 
library.

Arguments

None

Keywords

None

Version History

CDF 3.4.0

Introduced

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_LIB_INFO
============

The CDF_LIB_INFO procedure returns information about the CDF Library being 
used by this version of IDL. Information about the version of CDF used to 
create a particular CDF file can be obtained through CDF_DOC.

Examples

CDF_LIB_INFO, VERSION=V, RELEASE=R, COPYRIGHT=C, $

   INCREMENT=I

PRINT, 'IDL ', !version.release, 'uses CDF Library ', $

   V, R, I, FORMAT='(A,A,A,I0,".",I0,".",I0,A)'

PRINT, C

IDL Output

IDL 8.5 uses CDF Library 3.6.1

Common Data Format (CDF)

(C) Copyright 1990-2015 NASA/GSFC

Space Physics Data Facility

NASA/Goddard Space Flight Center

Greenbelt, Maryland 20771 USA

(Internet -- CDFSUPPORT@LISTSERV.GSFC.NASA.GOV)

Syntax

CDF_LIB_INFO [, COPYRIGHT =variable] [, INCREMENT=variable] $
             [, LEAPSEONDLASTUPDATED=variable] [, RELEASE=variable] $
             [, SUBINCREMENT=variable] [, VERSION=variable]

Arguments

None

Keywords

COPYRIGHT

A named variable in which the copyright notice of the CDF library that this 
version of IDL is using will be returned.

INCREMENT

A named variable in which the incremental number of the CDF library that this 
version of IDL is using will be returned.

LEAPSEONDLASTUPDATED

A named variable in which the date, in YYYYMMDD, of the last entry in the leap 
second table will be returned as a 32-bit integer. This date can be used to 
verify if a valid leap second table is being used either through internally or 
externally.

RELEASE

A named variable in which the release number of the CDF library that this 
version of IDL is using will be returned.

SUBINCREMENT

A named variable in which the sub incremental character of the CDF library that 
this version of IDL is using will be returned.

VERSION

A named variable in which the version number of the CDF library that this 
version of IDL is using will be returned.

Version History

Pre 4.0

Introduced

8.5	
Added LEAPSEONDLASTUPDATED keyword

See Also

CDF_DOC

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_OPEN
========

The CDF_OPEN function opens an existing Common Data Format file.

Examples

id = CDF_OPEN('open_close.cdf')   ; Open a file.

; ... other CDF_ commands ...

CDF_CLOSE, id ; Close the cdf file.

Syntax

Result = CDF_OPEN(Filename [, /READONLY] )

Return Value

If successful, the CDF ID for the file is returned.

Arguments

Filename

A scalar string containing the name of the file to be created. Note that if 
the desired filename has a .cdf ending, you can omit the extension and specify 
just the first part of the filename. For example, specifying “mydata” would 
open the file mydata.cdf.

Keywords

READONLY

Set this keyword to open the specified CDF file in readonly mode. Opening a 
file in readonly mode will result in significant performance improvement if 
there is a large amount of metadata and a large portion of the metadata is read.

Version History

Pre 4.0

Introduced

7.0.3

READONLY keyword added

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_PARSE_EPOCH16
=================

The CDF_PARSE_EPOCH16 function parses a properly-formatted input string into 
a double-complex value properly formatted for use as a CDF_EPOCH16 variable.

Note: CDF_EPOCH16 variables may be unparsed into a variety of formats using 
the CDF_ENCODE_EPOCH16 or CDF_EPOCH16 functions.

Example

test_string = '04-Dec-2005 20:19:18.176.214.648.000'

test_epoch = CDF_PARSE_EPOCH16(test_string)

CDF_EPOCH16, test_epoch, year, month, day, hour, min, sec, $

   milli, micro, nano, pico, /BREAKDOWN_EPOCH

HELP, test_string, test_epoch

PRINT, CDF_ENCODE_EPOCH16(test_epoch)

PRINT, year, month, day, hour, min, sec, milli, micro, nano, pico

 

IDL Prints:

TEST_STRING STRING = '04-Dec-2005 20:19:18.176.214.648.000'

TEST_EPOCH DCOMPLEX = ( 6.3300947e+10, 1.7621465e+11)

 

04-Dec-2005 20:19:18.176.214.648.000

2005  12  4  20  19  18  176  214  648  0

Syntax

Result = CDF_PARSE_EPOCH16(Epoch_string)

Note: Epoch string field can be a single string or an array of strings. Based 
      on the input, the output can be a single epoch value or an array of 
      epoch values, in DCOMPLEX.

Return Value

Returns the double-precision complex value of the input string properly 
formatted for use as a CDF_EPOCH16 variable.

Arguments

Epoch_string

A formatted string that will be parsed into a double precision complex value 
suitable to be used as a CDF_EPOCH16 value. The format of the date string is
one of the following styles:

DD-Mon-YYYY hh:mm:ss.ccc.uuu.nnn.ppp
YYYYmmdd.ttttttttttttttt
YYYYmmddhhmnss
YYYY-mm-ddThh:mn:ss.ccc.uuc.nnn.pppZ
YYYY-mm-ddThh:mn:ss.cccuucnnnppp

where:

Date Element

Represents

DD
the day of the month (1-31)

Mon
the abbreviated month name: (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, 
Nov, or Dec)

YYYY
the year (A.D.)

mm
the month (1-12)

hh
the hour (0-23)

mn
the minute (0-59)

ss
the second (0-59)

ccc
the millisecond (0-999)

uuu
the microsecond (0-999)

nnn
the nanosecond (0-999)

ppp
the picosecond (0-999)

ttttttttttttt
the subday

Keywords

None

Version History

6.3

Introduced

See Also

CDF_ENCODE_EPOCH16, CDF_EPOCH16

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_PARSE_EPOCH
===============

The CDF_PARSE_EPOCH function parses a properly-formatted input string into a 
double-precision value properly formatted for use as a CDF_EPOCH variable.

Note: CDF_EPOCH variables may be unparsed into a variety of formats using the 
CDF_ENCODE_EPOCH function.

Examples

test_string = '04-Dec-1995 20:19:18.176'

test_epoch = CDF_PARSE_EPOCH(test_string)

HELP, test_string, test_epoch

PRINT, CDF_ENCODE_EPOCH(test_epoch, EPOCH=0)

IDL Output

TEST_STRING STRING = '04-Dec-1995 20:19:18.176'

TEST_EPOCH DOUBLE = 6.2985328e+13

 

04-Dec-1995 20:19:18.176

Syntax

Result = CDF_PARSE_EPOCH(Epoch_string)

Note: Epoch string field can be a single string or an array of strings. Based
      on the input, the output can be a single epoch value or an array of epoch
      values.

Return Value

Returns the double-precision value of the input string properly formatted for 
use as a CDF_EPOCH variable.

Arguments

Epoch_string

A formatted string that will be parsed into a double precision value suitable 
to be used as a CDF_EPOCH value. The format of the date string is one of the
following styles:

DD-Mon-YYYY hh:mm:ss.ccc
YYYYmmdd.ttttttt
YYYYmmddhhmnss
YYYY-mm-ddThh:mn:ss.cccZ
YYYY-mm-ddThh:mn:ss.ccc

where:

Date Element

Represents

DD
the day of the month (1-31)

Mon
the abbreviated month name: (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, 
Nov, or Dec)

YYYY
the year (A.D.)

mm
the month (1-12)

hh
the hour (0-23)

mn
the minute (0-59)

ss
the second (0-59)

ccc
the millisecond (0-999)

ttttttt
the subday

For more information about CDF_EPOCH values, see “Data Types” in the CDF 
User’s Guide.

Keywords

None

Version History

4.0.1b

Introduced

See Also

CDF_ENCODE_EPOCH, CDF_EPOCH

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_PARSE_TT2000
================

The CDF_PARSE_TT2000 function parses a single or an array of input strings 
into an 8-byte integer (LONG64) value(s) for use as a CDF_TIME_TT2000 type 
variable. CDF_TIME_TT2000 variables may be encoded into a variety of formats 
using the CDF_ENCODE_TT2000 function or decomposed into date/time components 
using CDF_TT2000, /BREAKDOWN_EPOCH function.

Examples

test_string = '2005-12-04T20:19:18.176214648'

test_epoch = CDF_PARSE_TT2000(test_string)

CDF_TT2000,test_epoch, year, month, day, hour, min, sec, milli, $

                       micro, nano,/BREAKDOWN_EPOCH

 

HELP, test_string, test_epoch

PRINT, CDF_ENCODE_TT2000(test_epoch)

PRINT, year, month, day, hour, min, sec, milli, micro, nano

IDL Output

TEST_STRING STRING = '2005-12-04T20:19:18.176214648'

TEST_EPOCH LONG64 = 186999622360214648

2005-12-04T20:19:18.176214648

2005.0000 12.000000 4.0000000 20.000000 19.000000 18.000000 176.00000 214.00000

648.00000

Syntax

Result = CDF_PARSE_TT2000(Epoch_string)

Note: Epoch string field can be a single string or an array of strings. Based 
      on the input, the output can be a single epoch value or an array of epoch
      values.

Return Value

Returns a single value or an array (<= 2D) of 8-byte integer values of the 
input string(s).

Arguments

Epoch_string

A formatted string that is parsed into a double precision value to be used as 
a CDF_TIME_TT2000 data type. The format can be one of the following formats:

yyyy-MM-DDThh:mn:ss.cccuuunnn
dd-mon-yyyy hh:mn:ss.cccuuunnn
yyyyMMDD.tttttttttt
yyyyMMDDhhmnss
yyyy-MM-DDThh:mn:ss.cccuuunnnZ

The default format expected by CDF_PARSE_TT2000 is:

yyyy-MM-DDThh:mm:ss.cccuuunnn

where:

Date Element

Represents

YYYY

the year (A.D.)

MM

the month number (1-12)

mon

the abbreviated month name: (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct,
Nov, or Dec)

DD

the day of the month (1-31)

hh

the hour (0-23)

mm

the minute (0-59)

ss

the second (0-59|60 if leap second)

ccc

the millisecond (0-999)

uuu

the microsecond (0-999)

nnn

the nanosecond (0-999)

tttttttttt
the subday

Note: T is a CDF_TIME_TT2000 type 3 and 4 place holder. Z is a type 4 place
holder. For more information about 
CDF_TIME_TT2000 values, see “Data Types” in the CDF User’s Guide.

Keywords

None

Version History

CDF 3.4.0

Introduced

See Also

CDF_ENCODE_TT2000, CDF_TT2000

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_READCDF
===========

The CDF_READCDF function reads information from a Common Data Format file.
The retrieved information is presented in an IDL hash form. The hash consists
of up to four key/value pairs: 
  - The file's basic information;
  - Global attributes;
  - Variables' information, which includes variable's specification, attributes 
    and data;
  - Attributes without any data.

The value portion of the hash could be a hash itself, making the returned output
a structure of hash of the hashes (HOHs).

The keys in key/value pair are either fixed keys or variable keys. They are 
all case-sensitive strings or numbers (as for global entry number).
The fixed keys include "CDFInfo", "GlobalAttrs", "Variables" and 
"NoEntryAttrs" at the very top of the returned hash. In the middle, they are
"VarInfo", "VarAttrs" and "VarData" for each retrieved variable.
There are also other fixed keys, e.g., "Version", "Format", "DataType", 
"NumDims", etc., in the lower level hash for CDF or variable specification
information. 

The value for the key: "CDFInfo" is another hash that provides basic 
information about the CDF. 

The value for the key: "GlobalAttrs" is a hash that contains the global 
attributes. Each element in the hash uses the global attribute name as the 
key and its value is again another hash.  In this hash, each element has the 
entry number as the key and the entry as the value, a scalar or vector. 

The value for the key: "Variables" is a hash that contains the information
for all variables. Each element is the hash is keyed by the variable name. 
The value of the element is again another hash with up to three (3) elements.
The first element has the key of "VarInfo" with a value of a hash, which 
provides the specification about the variable. The second element has the 
key of "VarAttrs" with a value of a hash, which contains the variable 
attributes. Each element has the attribute name as the key and its 
attribute entry as its value, which can be a scalar or vector. The third
element has the key: "VarData". Its value is an object for the retrieved
variable data.

The value for the key: "NoEntryAttrs", if it exists, is another hash with up
two elements, each providing the name(s), as the value, of global or variable 
attributes that have no entry data. Those attribute names are presented in an
vector.

The variables keys are normally associated with attribute names, variable
names and entry numbers. 

A sample of the returned of a full hash from a CDF looks like this:

{
    "CDFInfo": {
        "FileName": "test",
        "NumGlobalAttrs": 5,
        "NumVariableAttrs": 5,
        "NumVariables": 2,
        "Format": "SINGLE_FILE",
        "Majority": "ROW_MAJOR",
        "Version": "3.8.1",
        ...
        ...
        ...
    },
    "GlobalAttrs": {
        "Project": {
            0: "LWS>Living With a Star"
        },
        "Source_name": {
            0: "RBSP-B>Radiation Belt Storm Probe B"
        },
        "Discipline": {
            0: "Space Physics>Magnetospheric Science"
        },
        "Data_type": {
            0: "H0>High Time Resolution"
        },
        "TEXT": {
            ...
            ...
            ...
        }
        ...
        ...
        ... 
    },
    "Variables": {
        "Latitude": {
            "VarInfo": {
                "DataType": "CDF_UINT1",
                "NumElems": 1,
                "RecVary": "VARY",
                "NumDims": 1,
                "DimSizes": [3],
                ...
                ...
            },
            "VarAttrs": {
                "VALIDMIN": -10,
                "VALIDMAX": 90,
                ...
                ...
                ...
            }
            "VarData": [[25, 54, 5], [15, 25, 35], [10, 28, 55]]
        },
        "Longitude": {
            "VarInfo": {
                "DataType": "CDF_INT2",
                "NumElems": 1,
                "RecVary": "VARY",
                "NumDims": 1,
                "DimSizes": [3],
                ...
                ...
            },
            "VarAttrs": {
                "VALIDMIN": 0,
                "VALIDMAX": 360,
                ...
                ...
                ...
            },
            "VarData": [[100, 200, 300], [67, 32, 27], [10, 20, 30], ...
        }
    }
}

Examples

; Open a CDF file:

file = 'rbsp-a_magnetometer_4sec-sm_emfisis-l3_20150622_v1.3.2.cdf'
id = CDF_OPEN(file)

; Retrieve the CDF_CHAR array as byte data:

cdf = CDF_READCDF (id, /string, /encoding)

Or, it can be called this way:

cdf = CDF_READCDF (file, /string, /encoding)

; Shows the keys

cdf.keys()

[
    "CDFInfo",
    "GlobalAttrs",
    "Variables"
]

; Show the CDF's basic information

cdf['CDFInfo']

{
    "FileName": "test3",
    "NumGlobalAttrs": 5,
    "NumVariableAttrs": 5,
    "NumVariables": 2,
    "Format": "SINGLE_FILE",
    "Majority": "ROW_MAJOR",
    "Version": "3.8.1",
    ...
    ...
    ...
}

; Show global attributes

cdf['GlobalAttrs']

{
    "Project": {
        0: "LWS>Living With a Star"
    },
    "Source_name": {
        0: "RBSP-B>Radiation Belt Storm Probe B"
    },
    "Discipline": {
        0: "Space Physics>Magnetospheric Science"
    },
    "Data_type": {
        0: "H0>High Time Resolution"
    },
    ...
    ...
    ...
}

; Show the variables

cdf['Variables'].keys()

[
    "Epoch",
    "UTC",
    "SCLOCK_Full",
    "OrbitNumber",
    "ET",
    "MidET",
    "StopET",
    ...
    ...
    ...
]

; Show Variable Epoch's information

cdf['Variables', 'Epoch'].keys()

[
    "VarInfo",
    "VarAttrs",
    "VarData"
]

; Show Epoch's basic information

cdf['Variables', 'Epoch', 'VarInfo']

{
    "DataType": "CDF_TIME_TT2000",
    "NumElems": 1,
    "RecVary": "VARY",
    "NumDims": 0,
    "NumWrittenRecs": 120148,
    "Compression": "GZIP.6"
}

; Show Epoch's attributes

cdf['Variables', 'Epoch', 'VarAttrs']

{
    "CATDESC": "Ephemeris Time of the start  of the accumulation for this measurement.",
    "FIELDNAM": "Epoch",
    "FILLVAL": -9223372036854775808,
    "LABLAXIS": "Epoch",
    "UNITS": "ns",
    "VALIDMIN": -315575942816000000,
    "VALIDMAX": 946728067183000000,
    "VAR_TYPE": "support_data",
    "SCALETYP": "linear",
    "VAR_NOTES": "This is the Ephemeris Time ....",
    "MONOTON": "INCREASE",
    "TIME_BASE": "J2000",
    "TIME_SCALE": "Terrestrial Time",
    "REFERENCE_POSITION": "Rotating Earth Geoid"
}

; Show Epoch's data

cdf['Variables', 'Epoch', 'VarData']

    465480068230000000
    465480068831000000
    465480069433000000
    465480070035000000
    465480070637000000
    465480071238000000
    465480071840000000
    ...
    ...
    ...

If there are no global attributes or variable attributes, then nothing will be
returned for hash GlobalAttrs or VarAttrs, respectively.

Note: This function will operate the CDF in zMODEon2 mode, which means all
      rVariables are handled as zVariables by removing those non-varying 
      dimensions from each rVAriabale. And, the zVariable ids are renumbered,
      after the rVariables'. If the CDF has only one type of variables, then
      the variable ids are not affected.
 
Syntax

cdf = CDF_READCDF ( Id, [, /DATAONLY] [, /ENCODING]  [, /GLOBALS] [, /STRING] 
                        [, /INFO]     [, /METADATA]  [, /NOENTRY] [, /VARATTRS]
                        [, /TO_COLUMN_MAJOR] [, VARS=...]
                        [, REC_COUNT=...]    [, REC_START=...]
                  )

Return Value

If successful, a hash with the requested information from a CDF is returned.

Arguments

Id

The CDF name or ID (returned from a previous call to CDF_OPEN or CDF_CREATE).
If a CDF name is entered, the file will be closed after the operation is done.

Keywords

DATAONLY

Set this keyword to read all variables' data, ignoring the basic information 
and metadata. The keys for the returned hash are the variable names.

ENCODING

Set this keyword to encode the variable's attributes or basic information. It
will convert variable's pad value or attributes' data to an encoded form. This
is mainly used for the values of CDF epoch type.

GLOBALS

Set this keyword to read only the global attributes from the CDF. The keys for
the returned hash are the global attribute names. If there is no global
attribute, an empty hash is returned.

INFO

Set this keyword to read the basic information about the CDF and all 
variables' specifications in it.

METADATA

Set this keyword to read only the metadata, the global attributes and variables'
attributes, from the CDF.

NOENTRY

Set this keyword to find out which global and variable attributes are defined,
but do not have any entry data. If there is no such attribute, an empty hash
is returned.

REC_COUNT

Set this keyword to the number of records to read. If not specified, all
records, starting from REC_START, will be read. At least one record will be 
returned, even it is a virtual record.

REC_START

Set this keyword to the starting record number to read. If not specified, the
variable's first record, record number 0, is assumed.

STRING

Set this keyword to return a variable's data of CDF_CHAR or CDF_UCHAR type from
the CDF file as a string rather than byte data. This keyword is ignored if the 
variable data 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-compliant CDF file, 
the dimensions defined in the variable attribute DEPEND_1, DEPEND_2, etc., will
match the returned data. This keyword is only applicable when reading full 
variable records.

VARATTRS

Set this keyword to read only variable attributes for all or the selected 
variable(s) from the CDF. The keys for the returned hash are the variable
names. If there is no metadata, an empty hash is returned. 

VARS

Specify the variable(s) to be read. The field value can be a scalar or an 
array of values. The value can be either a variable name(s) or variable id(s).
If a variable id(s) is used, make sure that zVariables' ids are properly 
renumbered, after the rVariables' ids, if the CDF has both types of variables. 
Only the information, variable's specification, metadata and/or data, from the
specified variable(s) will be returned.

Version History

Post 8.3

Introduced


© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.



CDF_READVARIABLE
================

The CDF_READVARIABLE function reads full information from a Common Data Format 
file's variable. The information includes the basic information, variable
attributes and all data. The retrieved info will be in a key/value hash table.
The value(s) can be a nested hash of hashes (HOHs).

There are fixed keys and variable keys. They are all case-sensitive strings.
The fixed keys include VarInfo, VarAttrs and VarData. The variables keys are 
variable attribute names and variable names.

Examples

; Open a CDF file (with rVariables of 2-by-3 dimensionality):

id = CDF_OPEN('a1_k0_mpa_20050804_v02')

; Retrieve the full information for variable: 'Epoch'

var = CDF_READVARIABLE (id, 'Epoch')

var.keys()
[
    "VarInfo",
    "VarAttrs",
    "VarData"
]

; Show the variable's basic information
PRINT, var['VarInfo']

DataType: CDF_EPOCH
NumElems:            1
RecVary: VARY
NumDims:            2
DimSizes:            2           3
DimVary: NOVARY ...
NumWrittenRecs:          991

; Shows the dimensional variances
PRINT, var['VarInfo','DimVary']

NOVARY NOVARY

; Shows the variable attributes
PRINT, var['VarAttrs']

FIELDNAM: Time
VALIDMIN:        62879846400000.000
VALIDMAX:        63776678399000.000
SCALEMIN:        62879846400000.000
SCALEMAX:        63776678399000.000
CATDESC: Time of proton collection (electrons 21.5 seconds later)
UNITS: ms
MONOTON: INCREASE
FILLVAL:   -9.9999999999999996e+30
VAR_TYPE: support_data
DICT_KEY:  
LABLAXIS: Epoch
AVG_TYPE:  
DISPLAY_TYPE:  
VAR_NOTES:

; Shows the variable data
PRINT, var['VarData'] 

   6.3290333e+13   6.3290333e+13
   6.3290333e+13   6.3290333e+13
   6.3290333e+13   6.3290333e+13

   6.3290333e+13   6.3290333e+13
   6.3290333e+13   6.3290333e+13
   6.3290333e+13   6.3290333e+13

   6.3290333e+13   6.3290333e+13
   6.3290333e+13   6.3290333e+13
   6.3290333e+13   6.3290333e+13

   6.3290333e+13   6.3290333e+13
   6.3290333e+13   6.3290333e+13
   6.3290333e+13   6.3290333e+13

   ....
   ....
   ....

; Turn on the zmode and encode the attributes of CDF epoch types. Its
; numDims becomes 0.
var2 = CDF_READVARIABLE('a1_k0_mpa_20050804_v02',0,/encoding,/zmode2)

; Non-varying dimensions are no shown...
PRINT, var2['VarInfo']         
DataType: CDF_EPOCH
NumElems:            1
RecVary: VARY
NumDims:            0
NumWrittenRecs:          991

; Show the encoded data for attributes: VALIDMIN/VALIDMAX/SCALEMIN/SCALEMAX
PRINT, var2['VarAttrs']

FIELDNAM: Time
VALIDMIN: 1992-08-01T00:00:00.000
VALIDMAX: 2020-12-31T23:59:59.000
SCALEMIN: 1992-08-01T00:00:00.000
SCALEMAX: 2020-12-31T23:59:59.000
CATDESC: Time of proton collection (electrons 21.5 seconds later)
UNITS: ms
MONOTON: INCREASE
FILLVAL:   -9.9999999999999996e+30
VAR_TYPE: support_data
DICT_KEY:  
LABLAXIS: Epoch
AVG_TYPE:  
DISPLAY_TYPE:  
VAR_NOTES:  

; Each record is a scalar...
PRINT, var2['VarData'] 

   6.3290333e+13
   6.3290333e+13
   6.3290333e+13
   6.3290333e+13
   6.3290333e+13
   6.3290333e+13
   ....
   ....
   ....

; Show the metadata from variable 'Epoch' and encode the epoch data
cdf_readvariable('a1_k0_mpa_20050804_v02','Epoch',/meta,/encod)
{
    "Epoch": {
        "FIELDNAM": "Time",
        "VALIDMIN": "1992-08-01T00:00:00.000",
        "VALIDMAX": "2020-12-31T23:59:59.000",
        "SCALEMIN": "1992-08-01T00:00:00.000",
        "SCALEMAX": "2020-12-31T23:59:59.000",
        "CATDESC": "Time of proton collection (electrons 21.5 seconds later)",
        "UNITS": "ms",
        "MONOTON": "INCREASE",
        "FILLVAL": -9.9999999999999996e+30,
        "VAR_TYPE": "support_data",
        "DICT_KEY": " ",
        "LABLAXIS": "Epoch",
        "AVG_TYPE": " ",
        "DISPLAY_TYPE": " ",
        "VAR_NOTES": " "
    }
}

Examples

; Open a CDF file:

id = CDF_OPEN('a1_k0_mpa_20050804_v02')

; Retrieve the information from variable 'Epoch', a rVariabale at variable
; id: 0.

var = CDF_READVARIABLE (id,'Epoch')

Or, it can be called this way:

var = CDF_READVARIABLE ('a1_k0_mpa_20050804_v02','Epoch')

; Shows the keys

var.keys()

IDL Output

[
    "VarInfo",
    "VarAttrs",
    "VarData"
]

Syntax

var = CDF_READVARIABLE ( Id, Variable, [, /DATAONLY] [, /ENCODING] [, /INFO]
                                       [, /REC_COUNT=...] [, /REC_START=...]
                                       [, /STRING] [, /TO_COLUMN_MAJOR]
                                       [, /VARATTRS] [, /ZMODE2] [, /ZVARIABLE]
                       )

Return Value

If successful, a hash with the requested information from the variable in a 
CDF is returned.

Arguments

Id

The CDF name or ID (returned from a previous call to CDF_OPEN or CDF_CREATE). If
a CDF name is entered, the file will be closed after the operation is done.

Variable

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

Keywords

DATAONLY

Set this keyword to ignore the variable's basic information and attributes, but
only read the variable's data. The key for the returned hash is the variable 
name.

ENCODING

Set this keyword to encode the variable's attributes or basic information. It
will convert variable's pad value or attributes' data to an encoded form. This
is mainly used for the values of CDF epoch type. 

INFO

Set this keyword to read only the basic information from a CDF and all variables
in it. The key for the returned hash is the variable name. 

REC_COUNT

Set this keyword to the number of records to read. If not specified, all
records, starting from REC_START will be read. At least one record will be
returned, even it is a virtual record.

REC_START

Set this keyword to the starting record number to read. If not specified, the
variable's first record, record number 0, is assumed.

STRING

Set this keyword to return a variable's data of CDF_CHAR or CDF_UCHAR type from the CDF file as a string rather than byte data. This keyword is ignored if the 
variable data 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-compliant CDF file,
the dimensions defined in the variable attribute DEPEND_1, DEPEND_2, etc., will match the returned data. This keyword is only applicable when reading full 
variable records.

VARATTRS

Set this keyword to read only the variable's metadata. The key for
the returned hash is the variable name. If there is no metadata for the
variable, an empty hash is returned.

ZMODE2

Set the zMODE on so a rVariable is going to be handled as a zVariable and its
non-varying dimension(s) will not be shown. ZMODE2 and ZVARIABLE are mutually
exclusive.

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. This keyword 
and ZMODE2 are mutually exclusive.

Version History

Post 8.3

Introduced


© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_SET_CDF27_BACKWARD_COMPATIBLE
=================================

The CDF_SET_CDF27_BACKWARD_COMPATIBLE procedure allows users of IDL version 
6.3 and later to create a CDF file that can be read by IDL 6.2 or earlier, or 
by CDF version 2.7.2 or earlier. By default, a CDF file created by IDL 6.3 or 
later cannot be read by earlier versions.

This procedure must be called prior to calling the CDF_CREATE function. It is 
useful if you need to create and share CDF files with colleagues who access 
CDF files using IDL version 6.2 or earlier, or using the CDF library version 
2.7.2 or earlier.

In CDF version 2.7.2 and earlier, the maximum CDF file size was 2 Gbytes. 
This limitation was lifted in CDF version 3.0 with the use of a 64-bit file 
offset. As a result, users who use a CDF library older than CDF version 3.0 
cannot read CDF files that were produced by CDF version 3.0 or a later release. 
CDF versions 3.0 and later can read files that were generated with any of the 
previous CDF releases.

Note: After calling this routine, the “backward compatible” setting specified 
persists either until this routine is called again or until the end of the IDL 
session.

Examples

Use the following command to create a CDF file that can be read by IDL 6.2 or 
earlier IDL versions.

CDF_SET_CDF27_BACKWARD_COMPATIBLE, /YES

id = CDF_CREATE('myfile.cdf')

CDF_CLOSE, id

Syntax

CDF_SET_CDF27_BACKWARD_COMPATIBLE [, /YES | /NO]

Arguments

None

Keywords

YES

Set this keyword to create a CDF file that can be read by IDL version 6.2 or 
earlier, or by CDF version 2.7.2 or earlier. If this keyword is set, the 
maximum file size is 2 Gbytes.

NO

Set this keyword to create a file that can only be read using IDL version 6.3 
or later or CDF version 3.0 or later. This is the default when a CDF file is 
created.

Version History

6.3

Introduced

 

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_SET_MD5CHECKSUM
===================

The CDF_SET_MD5CHECKSUM procedure calculates and inserts a MD5 checksum into 
a CDF file. If you use the /REMOVE keyword, a previously-inserted checksum is 
removed from the file.

By default, the checksums are not inserted into new files. Once the checksum 
is inserted into a particular file, a data integrity check of the file is 
performed every time it is opened. A new checksum is computed and stored when 
the file is closed. The overhead for this operation may be noticeable for large 
files. You may wish to remove the checksum once the integrity of the file has 
been verified.

Examples

The following example calculates and inserts a MD5 checksum inside of a CDF 
file.

id = CDF_CREATE('myfile.cdf')

CDF_SET_MD5CHECKSUM, id

CDF_CLOSE, id

Syntax

CDF_SET_MD5CHECKSUM, Id, [, /REMOVE]

Arguments

Id

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

Keywords

REMOVE

Remove a previously-created checksum from the CDF file.

Version History

 

7.0.3

Introduced


© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_SET_VALIDATE
================

The CDF_SET_VALIDATE procedure ensures that file data values are validated 
when CDF files are opened. The purpose of data checking is to uncover security 
problems (buffer overflow, for example) caused by compromised CDF files. The 
data validation process involves extra processing overhead, so turn data 
checking off if the files are known to be clean and uncompromised.

Examples

; Do not perform data validation when CDF files are opened.

CDF_SET_VALIDATE, /NO

id = CDF_OPEN('myfile.cdf')

; Process your CDF data

. . .

CDF_CLOSE, id

Syntax

CDF_SET_VALIDATE [, /YES | /NO]

Keywords

NO

Set this keyword to bypass data checking when CDF files are opened.

YES

Set this keyword to check file data when CDF files are opened. This is the 
default behavior.

Version History

8.0

Introduced

See Also

CDF_CONTROL, CDF_INQUIRE, CDF_VARINQ

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_TT2000
==========

The CDF_TT2000 procedure computes or breaks down CDF_TIME_TT2000 values in a 
CDF file. When computing an epoch, any missing value is considered to be zero.

If you supply a value for the Epoch argument and set the BREAKDOWN_EPOCH 
keyword, CDF_TT2000 will compute the values of the Year, Month, Day, etc. and 
insert the values into the named variables you supply. If you specify the Year 
(and optionally, the Month, Day, etc.) and set the COMPUTE_EPOCH keyword, 
CDF_TT2000 will compute the epoch and place the value in the named variable 
supplied as the Epoch parameter.

Note: You must set either the BREAKDOWN_EPOCH or COMPUTE_EPOCH keyword.
      The procedure allows input of an array of values.

Examples

To compute a single epoch value of September 20, 2005 at 3:05:46.27.02.156:

CDF_TT2000, epoch, 2005, 9, 20, 3, 5, 46, 27, 2, 156, /COMPUTE_EPOCH

To break down the given epoch value into standard date components:

CDF_TT2000, epoch, yr, mo, dy, hr, min, sec, milli, micro, nano, /BREAK

 

To compute an array of epoch values from the following three dates:

20-Sep-2005 03:05:46:156.111.222

20-Sep-2005 03:06:22:234.333.444

20-Sep-2005 03:07:12:345.555.666

yy = [2005, 2005, 2005]

mm = [9, 9, 9]

dd = [20, 20, 20]

hh = [3, 3, 3]

mn = [5, 6, 7]

ss = [46, 22, 12]

ms = [156, 234, 345]

us = [111, 333, 555]

ns = [222, 444, 666]

CDF_TT2000, epoch2, yy, mm, dd, hh, mn, ss, ms, us, ns, /COMPUTE_EPOCH


Since the year, month, day, hour fields are the same in this sample, the 
above command can also be written as:

CDF_TT2000, epoch2, 2005, 9, 20, 3, mn, ss, ms, us, ns, /COMPUTE_EPOCH


To break down the above vectorized epoch values into standard date components:

CDF_TT2000, epoch2, yr, mo, dy, hr, min, sec, milli, micro, nano, /BREAK

All yr, mo, dy, hr, min, sec, milli, micro, nano fields will be in array form.

Syntax

CDF_TT2000, Epoch, Year, Month, Day [, Hour, Minute, Second, Milli, $
                                       Micro, Nano] $
            [, /BREAKDOWN_EPOCH] [, /COMPUTE_EPOCH] [, /TOINTEGER]

Note: To compute the epoch, the date/time componments can be either a single 
      value or an array of values. The output Epoch field can be a scalar or
      an array of values. To break down the epoch, the Epoch field can be a 
      scalar or an array of epoch values. Based on the input, the date/time 
      componments can be a single value each, or an array of values.

Arguments

Epoch

The Epoch value to be broken down, or a named variable that will contain the 
computed epoch. The Epoch value is the number of nanoseconds since J2000 
(2000-01-01T12:00:00.000000000) with leap seconds included.

Note: CDF_TIME_TT2000 is based on J2000. It can only cover +/- 272 years from 
J2000. To convert CDF TT2000 epochs into date/times and vice versa, you should 
only use the CDF_TT2000 routine with either the BREAKDOWN_EPOCH or 
COMPUTE_EPOCH keyword.

Year

The year, such as 2012, or a named variable.

If COMPUTE_EPOCH is set, a four-digit integer representing the year.

If BREAKDOWN_EPOCH is set, a named variable that will contain the year.

Month

If COMPUTE_EPOCH is set, an integer between 1 and 12 representing the month. 
Alternately, you can set Month equal to zero, in which case the Day argument 
can take on a Day of the Year value between 1-366.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric month 
value.

Day

If COMPUTE_EPOCH is set, an integer between 1 and 31 representing the day of 
the month. Alternately, if the Month argument is set equal to zero, Day can be 
an integer between 1-366 representing the day of the year.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric day 
of the month value.

Hour

If COMPUTE_EPOCH is set, an integer between 0 and 23 representing the hour of 
the day.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric hour 
of the day value.

Minute

If COMPUTE_EPOCH is set, an integer between 0 and 59 representing the minute 
of the hour.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
minute of the hour value.

Second

If COMPUTE_EPOCH is set, an integer between 0 and 59 representing the second 
of the minute.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
second of the minute value.

Milli

If COMPUTE_EPOCH is set, an integer between 0 and 999 representing the 
millisecond. Alternately, if the Hour, Minute, and Second arguments are set 
all equal to zero, Milli can be an integer between 0-86400000 representing 
the millisecond of the day.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
millisecond value.

Micro

If COMPUTE_EPOCH is set, an integer between 0 and 999 representing the 
microsecond. Alternately, if the Hour, Minute, and Second arguments are set 
all equal to zero, Micro can be an integer between 0-86400000000 representing 
the microsecond of the day.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
microsecond value.

Nano

If COMPUTE_EPOCH is set, an integer between 0 and 999 representing the 
millisecond. Alternately, if the Hour, Minute, and Second arguments are set 
all equal to zero, Nano can be an integer between 0-86400000000000 representing 
the nanosecond of the day.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
nanosecond value.

Keywords

BREAKDOWN_EPOCH

Set this keyword to break down the value of the Epoch argument into its 
component parts, storing the resulting year, month, day, etc. values in the 
variables specified by the corresponding arguments.

COMPUTE_EPOCH

Set this keyword to compute the value of Epoch from the values specified by the 
Year, Month, Day, etc. arguments.

TOINTEGER

Set this keyword when an epoch value(s) is broken down to date/time components 
(with BREAKDOWN_EPOCH keyword). If this keyword is set, all components will be 
in integer, instead of their default of doubles.

Version History

CDF 3.4.0

Introduced

See Also

CDF_ENCODE_TT2000, CDF_PARSE_TT2000

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


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, you should 
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.

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.

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

Version History

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.

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_VARDELETE
=============

The CDF_VARDELETE procedure deletes a variable from a SINGLE_FILE CDF file. 
Note that the variable’s entries are also deleted, and that the variables that 
numerically follow the deleted variable within the CDF file are automatically 
renumbered. CDF rVariables and zVariables are counted separately within CDF 
files. Attempting to delete a variable from a MULTI_FILE format CDF file will 
result in a warning message.

Examples

cid = CDF_CREATE('DEMOvardelete',/SINGLE_FILE)

 

; Create 3 zVariables and 1 rVariable:

var1_id = CDF_VARCREATE(cid, 'rVAR1', /CDF_FLOAT)

var2_id = CDF_VARCREATE(cid, 'zVAR1', /CDF_INT4, /REC_NOVARY, $

   /ZVARIABLE)

var3_id = CDF_VARCREATE(cid, 'zVAR2', /CDF_CHAR, [2,10], $

   NUMELEM=10, DIM=[5,5])

var4_id = CDF_VARCREATE(cid, 'zVAR3' ,/CDF_REAL8, /ZVARIABLE)

 

; Check the number of variables:

info = CDF_INQUIRE(cid)

HELP, info.nzvars, info.nvars

 

; Delete the first and third zvariables:

CDF_VARDELETE, cid, 'zVAR1', /ZVARIABLE

CDF_VARDELETE, cid, 1, /ZVARIABLE

 

; CAUTION: Remember the variable numbers are zero-based

; and are automatically renumbered.

 

info = CDF_INQUIRE(cid)

HELP, info.nzvars, info.nvars

varinfo = CDF_VARINQ(cid, 0, /ZVARIABLE)

; check on zVAR2

HELP, varinfo, /STRUCTURE

 

CDF_DELETE, cid

IDL Output

<Expression> LONG = 3

<Expression> LONG = 1

 

<Expression> LONG = 1

<Expression> LONG = 1

 

** Structure <400a3b40>, 8 tags, length=48, refs=1:

   IS_ZVAR INT 1

   NAME STRING    'zVAR2'

   DATATYPE STRING    'CDF_CHAR'

   NUMELEM LONG 10

   RECVAR STRING    'VARY'

   DIMVAR BYTE Array(2)

   ALLOCATERECS LONG Array(2)

   DIM LONG Array(1)

Syntax

CDF_VARDELETE, Id, Variable [, /ZVARIABLE]

Arguments

Id

The CDF ID of the file containing the Variable to be deleted, returned from a 
previous call to CDF_OPEN or CDF_CREATE.

Variable

A string containing the name of the variable to be deleted OR the variable 
number to be deleted. Variable numbers are 0-based in IDL. zVariables and 
rVariables are counted separately in CDF files.

Keywords

ZVARIABLE

Set this keyword if the Variable is a zVariable and was passed by number. The 
default is to assume that Variable is an rVariable.

Version History

4.0.1b

Introduced

See Also

CDF_ATTDELETE, CDF_CONTROL, CDF_VARCREATE, CDF_VARINQ

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_VARGET1
===========

The CDF_VARGET1 procedure reads one value from a CDF file variable.

Examples

See the example for CDF_VARCREATE.

Syntax

CDF_VARGET1, Id, Variable, Value [, OFFSET=vector] [, REC_START=record] $
             [, /STRING{data in CDF file must be type CDF_CHAR or CDF_UCHAR}] $
             [, /ZVARIABLE]

Arguments

Id

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

Variable

A string containing the name or an integer containing the index of the 
variable being inquired.

Value

A named variable in which the value of the variable is returned.

Keywords

OFFSET

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

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. 

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

See the example for CDF_VARCREATE.

Version History

Pre 4.0

Introduced

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_VARGET
==========

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. Note: A number of 0 is 
accepted, which indicates to read, from the REC_START, till the end of the 
written record. One (1) record is assumed if REC_START is greater than the
last of written record number.

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

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_VARINQ
==========

The CDF_VARINQ function returns a structure containing information about the 
specified variable in a Common Data Format file.

Examples

See the example for CDF_VARGET.

Syntax

Result = CDF_VARINQ( Id, Variable [, /ZVARIABLE] )

Return Value

The returned structure has the form:

{ IS_ZVAR:0, NAME:"", DATATYPE:"", NUMELEM:0L, $

   RECVAR:"", DIMVAR:BYTARR(...) [, DIM:LONARR(...)]}

Note: The DIM field is included in the structure only if IS_ZVAR is one.

Explanation of the Structure Tags

The following table provides structure tag information.

Tag

Description

IS_ZVAR

This field will contain a 1 if the variable is a zVariable or a 0 if it is an 
rVariable.

NAME

The name of the variable.

DATATYPE

A string describing the data type of the variable. The string has the form 
‘CDF_XXX’ where XXX is FLOAT, DOUBLE, EPOCH, UCHAR, etc.

NUMELEM

The number of elements of the data type at each variable value. This is always 
1 except in the case of string type variables (CDF_CHAR, CDF_UCHAR).

RECVAR

A string describing the record variance of the variable. This is either the 
string ‘VARY’ or ‘NOVARY’.

DIMVAR

An array of bytes. The value of each element is zero if there is no variance 
with that dimension and one if there is variance. For zero-dimensional CDFs, 
DIMVAR will have one element whose value is zero.

DIM

An array of longs. The value of each element corresponds to the dimension of 
the variable. This field is only included in the structure if the variable is 
a zVariable.

Arguments

Id

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

Variable

A string containing the name or an integer containing the index of the variable 
being inquired.

Keywords

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.

Version History

Pre 4.0

Introduced

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_VARNUM
==========

The CDF_VARNUM function returns the variable number associated with a given 
variable name in a Common Data Format file.

Examples

See the example for CDF_VARGET.

Syntax

Result = CDF_VARNUM( Id, VarName [, IsZVar] )

Return Value

Returns the variable number of a specified variable name. If the specified 
variable cannot be found in the CDF file, CDF_VARNUM returns the scalar -1.

Arguments

Id

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

VarName

A string containing the name of the variable.

IsZVar

A named variable into which CDF_VARNUM will place a 1 to indicate that the 
referenced variable is a zVariable or a 0 to indicate that it is an rVariable.

Keywords

None

Version History

Pre 4.0

Introduced

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_VARPUT
==========

The CDF_VARPUT procedure writes a value to a variable in a Common Data Format 
file. This function provides equivalent functionality to the C routines 
CDFvarPut and CDFvarHyperPut.

Examples

id= CDF_CREATE('mycdf', [5,10], /NETWORK_ENCODING, /ROW_MAJOR)

varid= CDF_VARCREATE(id, 'V1', [1,1], /CDF_FLOAT, /REC_VARY)

To write the value 42.0 into record 12, third row, fourth column:

CDF_VARPUT, id, varid, 42, REC_START=12, OFFSET=[2,3]

Syntax

CDF_VARPUT, Id, Variable, Value [, COUNT=vector] [, INTERVAL=vector] $
                                [, OFFSET=vector] [, REC_INTERVAL=value] $
                                [, REC_START=record] [, /ZVARIABLE]

Arguments

Id

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

Variable

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

Value

The value to write. If the value has 1 more dimension than the CDF, multiple 
records will be written.

Keywords

COUNT

An optional vector containing the counts to be used in writing Value. Note that 
counts do not have to match the dimensions of Value. The default count is to 
use the dimensions of Value.

INTERVAL

A vector specifying the interval between values in each dimension. The default 
value is 1 in 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 in each dimension.

REC_INTERVAL

The interval between records being written when writing multiple records. The 
default value is 1.

REC_START

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

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.

Version History

Pre 4.0

Introduced

See Also

CDF_VARCREATE, CDF_VARINQ, CDF_VARGET

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.


CDF_VARRENAME
=============

The CDF_VARRENAME procedure renames an existing variable in a Common Data 
Format file.

Examples

See the example for CDF_VARGET.

Syntax

CDF_VARRENAME, Id, OldVariable, NewName [, /ZVARIABLE]

Arguments

Id

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

OldVariable

A string containing the current name of the variable or the variable number 
to be renamed.

NewName

A string containing the new name for the variable.

Keywords

ZVARIABLE

If OldVariable 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 OldVariable is an rVariable ID.

Version History

Pre 4.0

Introduced

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.