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 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: } 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, 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. CDF_EPOCH ========= The CDF_EPOCH procedure computes or breaks down CDF_EPOCH 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_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. The procedure allows input of an array of values. Initially, it could only handle a scalar. Examples To compute the epoch value of September 20, 1992 at 3:00 am: 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 Syntax CDF_EPOCH, Epoch, Year [, Month, Day, Hour, Minute, Second, Milli] $ [, /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 milliseconds since 01-Jan-0000 00:00:00.000 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 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. 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. 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 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_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. Initially, it could only handle a scalar. 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 LONG = 3 LONG = 1 LONG = 1 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.