Please see IDL help for the definition. 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. Syntax Result = CDF_ATTEXISTS( Id, Attribute [, EntryNum] [, /ZVARIABLE] ) Return Value Returns TRUE (1) if the specified attribute exists or FALSE (0) if it does noti 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 attributei 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. 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 Version History See Also CDF_ATTCREATE, CDF_ATTGET, CDF_ATTDELETE, CDF_ATTINQ, CDF_ATTPUT, CDF_ATTRENAME CDF_ATTGET_ENTRY -------------------------------------------------------------------------------- The CDF_ATTGET_ENTRY procedure reads a variable attribute's entry from a CDF file. Syntax CDF_ATTGET_ENTRY, Id, Attribute, EntryNum, Value, AttributeEntryType, Value, Status [,CDF_TYPE= attribute_entry_datatype] [, ATTRIBUTE_NAME=attribute_name] [,/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 from which attribute entry is retrieved. 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. AttributeEntryType The data type of the requested attribute entry Value A named variable in which the value of the attribute is returned. Status Return status. 1 is returned if the requested attribute exist and its entry is retrieved. Otherwise, 0 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_REAL4, CDF_FLOAT, CDF_REAL8, CDF_DOUBLE, CDF_EPOCH, or CDF_EPOCH16. If the type cannot be determined, "UNKNOWN" is returned. ATTRIBUTE_NAME 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 is to assume that EntryNum is an rVariable ID. Note: the attribute must have a scope of VARIABLE_SCOPE. Examples -------- id = cdf_open('test.cdf') inq = cdf_inquire(id) ; Read all the variable attribute entries. for var_num = 0, inq.nzvars-1 do begin for attr_num = 0, inq.natts-1 do begin cdf_attget_entry, id, attr_num, var_num, att_type, value, status, /zvar, cdf_type=cdf_type, attribute_name=att_name if status ne 1 then continue print, "attr_name = ", att_name, ", ", cdf_type, ", ", value endfor endfor CDF_ATTGET -------------------------------------------------------------------------------- The CDF_ATTGET procedure reads an attribute entry from a CDF file. 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_REAL4, CDF_FLOAT, CDF_REAL8, CDF_DOUBLE, CDF_EPOCH, or CDF_EPOCH16. 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. Examples ; Open the CDF file created in the CDF_ATTPUT example: id = CDF_OPEN('foo') CDF_ATTGET, id, 'Att2', '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. Version History Introduced: 6.1 Please see IDL help for the definition. Please see IDL help for the definition. Please see IDL help for the definition. Please see IDL help for the definition. Please see IDL help for the definition. 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_NEGTOPOSFP0_MODE=variable] [, GET_NUMATTRS=variable] [, GET_READONLY_MODE=variable] [, GET_RVAR_CACHESIZE=variable] [, GET_VAR_INFO=variable] [, GET_SPARSERECORDS=value] [, GET_ZMODE=variable] [, GET_ZVAR_CACHESIZE=variable] [, GET_LEAPSECONDLASTUPDATED=variable] [, SET_CACHESIZE=value] [, SET_EXTENDRECS=records] [, SET_INITIALRECS=records] [, /SET_NEGTOPOSFP0_MODE] [, SET_PADVALUE=value] [, /SET_READONLY_MODE] [, SET_RVAR_CACHESIZE=value{See Note}] [, SET_RVARS_CACHESIZE=value{See Note}] [, SET_ZMODE={0 | 1 | 2}] [, SET_SPARSERECORDS=value] [, SET_ZVAR_CACHESIZE=value{See Note}] [, SET_ZVARS_CACHESIZE=value{See Note}] [, VARIABLE=name or index] [, SET_LEAPSECONDLASTUPDATED=value] [, /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_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 readonly 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 the variable's sparseness. The returned is a string with a value of: ‘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. 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. GET_LEAPSECONDLASTUPDATED Set this keyword to the open CDF that will retrieve the field that stores the leap second last updated date, in YYYYMMDD form, e.g., 20150701. This infomation is only relevant to CDF TT2000 variable data. Its value represents the latest leap second was added to the leap second table when this CDF was crated. This value can also be zero (0), meaning the table was not used to create the CDF, or negative 1 (-1) for older CDFs that have not had the field set. 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_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 the sparserecords value for the current variable. The valid values are: 0 or "no_sparserecords", 1 or "pad_sparserecords"), 2 or "prev_sparserecords". It can be in either a numeric or string form. For discussion about using sparseness with CDF files, see “Sparseness” in the CDF User’s Guide. 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. SET_LEAPSECONDLASTUPDATED Set this keyword to the open CDF that will reset the field that stores the leap second last updated date, in YYYYMMDD form, 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 not being used to create the CDF. 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 See Also CDF_CREATE, CDF_INQUIRE CDF_CREATE ---------- The CDF_CREATE function creates a new Common Data Format file with the given filename. 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. If you work in a single-platform environment most of the time, select HOST_ENCODING for 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 NETWORK_ENCODING (the default). Specifying the target architecture provides maximum performance on that architecture; specifying NETWORK_ENCODING provides maximum flexibility. For more discussion on CDF encoding/decoding methods and combinations, see sections 2.2.8 ("Encoding") and 2.2.9 ("Decoding") of the version 2.7 CDF User's Guide. Syntax Result = CDF_CREATE( Filename, [Dimensions] [, /CLOBBER] [, /MULTI_FILE | , /SINGLE_FILE] [, /COL_MAJOR | , /ROW_MAJOR] [Encoding keyword] [Decoding Keyword] ) Encoding Keywords (optional): [, /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] Decoding Keywords (Optional): [, /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] 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 will attempt to delete this bad file. If it fails, causing IDL to display an error message, 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. ROW_MAJOR Set this keyword to specify row major (C-like) array ordering for variable storage. This is the default. 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 in 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. and it is less efficient than the SINGLE_FILE format. See section 2.2.7 ("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. 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' 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 section 2.2.7 ("Format") of 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. 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. 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. 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. 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. 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 Version History Introduced: Pre 4.0 Please see IDL help for the definition. CDF_ENCODE_EPOCH16 ------------------ The CDF_ENCODE_EPOCH16 function encodes a single or an array of CDF_EPOCH16 value(s) into the standard date and time character string(s). The default format of the string is dd-mmm-yyyy hh: mm:ss.ccc.uuu.nnn.ppp where dd is the day of the month (1-31), mmm is the month (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec), yyyy is the year, hh is the hour (0-23), mm is the minute (0-59), ss is the second (0-60 if leap second), ccc is the millisecond (0-999), uuu is the microsecond (0-999), nnn is the nanosecond (0-999), and ppp is the picosecond (0-999). Syntax Result = CDF_ENCODE_EPOCH16(Epoch16 [, EPOCH={0 | 1 | 2 | 3}]) Return Value Returns the string(s) representation of the given CDF_EPOCH16 value(s). Arguments Epoch16 A scalar or an array (<= 2D) CDF_EPOCH16 value(s). Keywords EPOCH=, where the default epoch_mode is 0. EPOCH=0 : returns a date in dd-mmm-yyyy hh:mm:ss.ccc.uuu.nnn.ppp where dd is the day of the month (1-31), mmm is the month (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, or Dec), yyyy is the year, A.D, hh is the hour (0-23), mm is the minute (0-59), ss is the second (0-60 if leap second), ccc is the millisecond (0-999), uuu is the microsecond (0-999), nnn is the nanosecond (0-999), and ppp is the picosecond (0-999). EPOCH=1 : returns a date in yyyymmdd.ttttttttttttttt where yyyy is the year, mm is the month (1-12), dd is the day of the month (1-31), and ttttttttttttttt is the fraction of the day (e.g. 500000000000000 is 12 'oclock noon). EPOCH=2 : returns a date in yyyymmddss where yyyy is the year, mm is the month (1-12), dd is the day of the month (1-31), and ss is the second (0-59). EPOCH=3 : returns a date in yyyy-mm-ddThh:mm:ss.ccc.uuu.nnn.pppZ yyyy is the year, mm is the month (1-12), dd is the day of the month (1-31), hh is the hour (0-23), mm is the minute (0-59), ss is the second (0-60 if leap second), ccc is the millisecond (0-999), uuu is the microsecond (0-999), nnn is the nanosecond (0-999), and ppp is the picosecond (0-999). 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 Version History Introduced: CDF 3.4.0 See Also CDF_PARSE_EPOCH16, CDF_EPOCH16 CDF_ENCODE_EPOCH ---------------- The CDF_ENCODE_EPOCH function encodes a single or an array of CDF_EPOCH value(s) into the standard date and time character string(s). The format of the string is default as dd-mmm-yyyy hh: mm:ss.ccc where dd is the day of the month (1-31), mmm is the month (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec), yyyy is the year, hh is the hour (0-23), mm is the minute (0-59), ss is the second (0-60 if leap second), and ccc is the millisecond (0-999). Syntax Result = CDF_ENCODE_EPOCH(Epoch [, EPOCH={0 | 1 | 2 | 3}]) Return Value Returns the string(s) representation of the given CDF_EPOCH value(s). Arguments Epoch A scalar or any array (<=2D) CDF_EPOCH value(s). Keywords EPOCH=, where the default epoch_mode is 0. EPOCH=0 : returns a date in dd-mmm-yyyy hh:mm:ss.ccc where dd is the day of the month (1-31), mmm is the month (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, or Dec), yyyy is the year, A.D, hh is the hour (0-23), mm is the minute (0-59), ss is the second (0-60 if leap second), and ccc is the millisecond (0-999). EPOCH=1 : returns a date in yyyymmdd.ttttttt where yyyy is the year, mm is the month (1-12), dd is the day of the month (1-31), and ttttttt is the fraction of the day (e.g. 5000000 is 12 'oclock noon). EPOCH=2 : returns a date in yyyymmddss where yyyy is the year, mm is the month (1-12), dd is the day of the month (1-31), and ss is the second (0-59). EPOCH=3 : returns a date in yyyy-mm-ddThh:mm:ss.cccZ yyyy is the year, mm is the month (1-12), dd is the day of the month (1-31), hh is the hour (0-23), mm is the minute (0-59), ss is the second (0-60 if leap second), and ccc is the millisecond (0-999). Examples test_string = '04-Dec-2005 20:19:18.176' test_epoch = CDF_PARSE_EPOCH(test_string) PRINT, CDF_ENCODE_EPOCH(test_epoch) IDL Output 04-Dec-2005 20:19:18.176 Version History Introduced: CDF 3.4.0 See Also CDF_PARSE_EPOCH, CDF_EPOCH CDF_ENCODE_TT2000 ----------------- The CDF_ENCODE_TT2000 function encodes a single 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 a ISO 8601 format as yyyy-mm-ddThh:mm:ss.cccuuunnn where yyyy is the year, mm is the month (1-12), dd is the day of the month (1-31), hh is the hour (0-23), mm is the minute (0-59), ss is the second (0-60 if leap second), and ccc is the millisecond (0-999), uuu is the microsecond (0-999), and nnn is the nanosecond (0-999). Syntax Result = CDF_ENCODE_TT2000(Epoch [, EPOCH={0 | 1 | 2 | 3}]) Return Value Returns the string(s) representation of the given CDF_TIME_TT2000 value(s). Arguments Epoch A scalar or an array (<= 2D) of CDF_TIME_TT2000 value(s). Keywords EPOCH=, where the default epoch_mode is 3. EPOCH=0 : returns a date in dd-mmm-yyyy hh:mm:ss.ccccccccc where dd is the day of the month (1-31), mmm is the month (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, or Dec), yyyy is the year, A.D, hh is the hour (0-23), mm is the minute (0-59), ss is the second (0-60 if leap second), and ccccccccc is the millisecond (000-999), microsecond (000-999) and nanosecond (000-999). EPOCH=1 : returns a date in yyyymmdd.tttttttttt where yyyy is the year, mm is the month (1-12), dd is the day of the month (1-31), and tttttttttt is the fraction of the day (e.g. 5000000000 is 12 o'clock noon). EPOCH=2 : returns a date in yyyymmddss where yyyy is the year, mm is the month (1-12), dd is the day of the month (1-31), and ss is the second (0-59). EPOCH=3 : returns a date in yyyy-mm-ddThh:mm:ss.ccccccccc yyyy is the year, mm is the month (1-12), dd is the day of the month (1-31), hh is the hour (0-23), mm is the minute (0-59), ss is the second (0-60 if leap second), and ccccccccc is the millisecond (000-999), microsecond (000-999) and nanosecond (000-999). Examples test_string = '2005-12-04T20:19:18.176321123' test_epoch = CDF_PARSE_TT2000(test_string) PRINT, CDF_ENCODE_TT2000(test_epoch) CDF_TT2000, test_epoch2, 2005, 12, 4, 20, 19, 18, 176, 321, /compute PRINT, CDF_ENCODE_TT2000(test_epoch2, epoch=0) IDL Output 2005-12-04T20:19:18.176321123 04-Dec-2005 20:19:18.176321123 Version History Introduced: CDF 3.4.0 See Also CDF_PARSE_TT2000, CDF_TT2000 CDF_EPOCH16 ----------- The CDF_EPOCH16 procedure computes or breaks down a single or an array of CDF_EPOCH16 value(s) in a CDF file. When computing an epoch, any missing value is considered to be zero. If you supply a scalar or an array of value(s) 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.) in a scalar or array and set the COMPUTE_EPOCH keyword, CDF_EPOCH16 will compute the epoch and place the value(s) in the named variable supplied as the Epoch parameter. Note: You must set either the BREAKDOWN_EPOCH or COMPUTE_EPOCH keyword. Syntax CDF_EPOCH16, Epoch, Year [, Month, Day, Hour, Minute, Second, Milli, Micro, Nano, Pico] [, /BREAKDOWN_EPOCH] [, /COMPUTE_EPOCH] Arguments Epoch A single or an array (<= 2D) Epoch value(s) to be broken down, or a named variable into which 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 CDF epochs into date/times and vice versa, you should only use the CDF_EPOCH16 routine with either the BREAKDOWN_EPOCH or COMPUTE_EPOCH keyword. Year The year(s) (such as 1992) or a named variable. Month The month(s) (1-12) or a named variable. You can also set the Month argument equal to zero, in which case the Day argument can take on any value between 1-366; this number is interpreted as the "Day of the Year" rather than a "Day of the Month". Day The day(s) (1-31) or a named variable. If the Month argument is set equal to zero, Day can be set to any value between 1-366. Hour The hour(s) (0-23) or a named variable. Minute The minute(s) (0-59) or a named variable. Second The second(s) (0-59) or a named variable. Milli The millisecond(s) (0-999) or a named variable. Micro The microsecond(s) (0-999) or a named variable. Nano The nanosecond(s) (0-999) or a named variable. Pico The picosecond(s) (0-999) or a named variable. Keywords BREAKDOWN_EPOCH If this keyword is set, Epoch is a value which will broken down and the resulting Year, Month, Day, etc. are returned in the remaining parameters which must be named variables. COMPUTE_EPOCH If this keyword is set, Epoch is a named variable into which the epoch is placed and the other parameters are values which will be used to compute the epoch. Examples To compute the epoch value of September 20, 2005 at 3:05:46:02:156: CDF_EPOCH16, epoch, 2005, 9, 20, 3, 5, 46, 27, 2, 156, /COMPUTE_EPOCH To break down the given epoch value into standard date components: CDF_EPOCH16, epoch, yr, mo, dy, hr, min, sec, milli, micro, nano, /BREAK To compute an array of epoch values from the following three dates: 20-Sep-2005 03:05:46:156.111.222.333, 20-Sep-2005 03:06:22:234.444.555.666, 20-Sep-2005 03:07:12:345.777.888.999: 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, 444, 777] ns = [222, 555, 666] ps = [333, 666, 999] CDF_EPOCH16, epoch2, yy, mm, dd, hh, mn, ss, ms, us, ns, ps, /COMPUTE Since the year, month, day, hour fields are the same in this sample, alternatively, the above command can be written as: CDF_EPOCH16, epoch2, 2005, 9, 20, 3, mn, ss, ms, us, ns, ps, /COMPUTE To break down the above vectorized epoch values into standard date components: CDF_EPOCH16, epoch2, yr, mo, dy, hr, min, sec, milli, micro, nanso, pico, /BREAK All yr, mo, dy, hr, min, sec, milli, micro, nano and pico fields will be in an array. Version History Introduced: CDF 3.4.0 See Also CDF_ENCODE_EPOCH16, CDF_PARSE_EPOCH16 CDF_EPOCH_COMPARE ----------------- The CDF_EPOCH_COMPARE function compares a source epoch, either a scalar or an array of epoch values (date and time), against a base epoch, also a scalar or an array of values. The epoch can be one of the CDF formats, CDF_EPOCH, CDF_EPOCH16 and CDF_TIME_TT2000. While data of type CDF_EPOCH and CDF_EPOCH16 can be compared with each other, data in CDF_TIME_TT2000 can only be compared with the data of 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, 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. Calling the function with two arguments: It returns a scalar value or an array values of integer of 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. Returns: A scalar or array of integers of 1 : if epoch1 > baseepoch 0 : if epoch1 = baseepoch -1 : if epoch1 < baseepoch Calling the function with three arguments: It returns a scalar value or an array values of integer of 1 or 0. If the value of the source epoch falls within the starting and ending epoch 1 is set. Otherwise, 0 is set. Returns: A scalar or array of integers of 1 : if baseepoch <= epoch1 <= endepoch 0 : otherwise Syntax Result = CDF_EPOCH_COMPARE(epoch, baseepoch [,endepoch]) Arguments epoch A single or an array of epoch value(s) returned from call to CDF_EPOCH,/compute, CDF_EPOCH16,/compute for CDF_EPOCH or CDF_EPOCH16 data type, or 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 call to CDF_EPOCH,/compute, CDF_EPOCH16,/compute for CDF_EPOCH or CDF_EPOCH16 data type, or 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 call to CDF_EPOCH,/compute, CDF_EPOCH16,/compute for CDF_EPOCH or CDF_EPOCH16 data type, or CDF_TT2000,/compute for CDF_TIME_TT2000 data type, CDF_VARGET, or CDF_VARGET1. This field has to be of the same data type and dimensionality as baseepoch. Keywords None 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 Version History Introduced: CDF V3.4.0 CDF_EPOCH_DIFF -------------- The CDF_EPOCH_DIFF function computes the difference between the source epoch, either a scalar or an array of epoch values (date and time), against a base epoch, also a scalar 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 only be compared with the data of the same type. If the base epoch is a scalar, it is used to compute the differences with all values in the source epoch. If the base epoch is an array, same element in the source and base epoch array is compared. It returns a scalar value or an array of values, depending on the source epoch, in milliseconds or microseconds for CDF_EPOCH and CDF_EPOCH16 data types, or nanoseconds for CDF_TIME_TT2000 data type. Syntax Result = CDF_EPOCH_DIFF(epoch1, epoch2 [,/MILLI_SECONDS | ,/MICRO_SECONDS]) Arguments epoch1 A single or an array epoch value(s) returned from call to CDF_EPOCH,/compute, or CDF_EPOCH16,/compute for CDF_EPOCH or CDF_EPOCH16 data type, or CDF_TT2000,/compute for CDF_TIME_TT2000 data type, CDF_VARGET, or CDF_VARGET1. epoch2 A single or an array epoch value(s) returned from call to CDF_EPOCH,/compute, or CDF_EPOCH16,/compute for CDF_EPOCH or CDF_EPOCH16 data type, or CDF_TT2000,/compute for CDF_TIME_TT2000 data type, CDF_VARGET, or CDF_VARGET1. Keywords MILLI_SECONDS The default for CDF_EPOCH and CDF_EPOCH16 data comparison and not applicable to CDF_TIME_TT2000 data type. The resolution is in milliseconds. It indicates that the sub-millisecond portions are ignored for CDF_EPOCH16 data type. It has no effect to CDF_EPOCH data type. MICRO_SECONDS The resolution is in microseconds and the sub-microseconds portions of the data are ignored for CDF_EPOCH16 data type. CDF_EPOCH data is expanded to microseconds, but is not applicable to CDF_TIME_TT2000. 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_diff(ep,base) help, ret ; For CDF_TIME_TT2000 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_diff(ep2,base2) help, ret2 Version History Introduced: CDF V3.4.0 CDF_EPOCH_TOJULDAYS ------------------- The CDF_EPOCH_TOJULDAYS function converts CDF epoch value(s), in CDF_EPOCH, CDF_EPOCH16 or CDF_TIME_TT2000 data type, to Julian day(s). Each returned Julian day is in double, similar to what IDL's JULDAY returns. Optionally, the returned days can be in string of ISO 8601 format. Syntax Result = CDF_EPOCH_TOJULDAYS (epoch[, /STRING]) Arguments epoch An epoch value(s) returned from CDF_EPOCH,/compute, CDF_EPOCH16,/compute, CDF_TT2000,/compute, CDF_VARGET, or CDF_VARGET1. Keywords STRING Signal that the returned date(s) in ISO 8601 format string Examples cdf_varget, id, "Epoch", epoch, rec_count=1000,/zvariable ret = cdf_epoch_tojuldays (epoch) ret2 = cdf_epoch_tojuldays (epoch, /string) Version History Introduced: CDF V3.4.0 See Also CDF_EPOCH, CDF_EPOCH16, CDF_TT2000 CDF_EPOCH --------- The CDF_EPOCH procedure computes or breaks down a single or an array of CDF_EPOCH value(s) in a CDF file. When computing an epoch(s), any missing value is considered to be zero. If you supply a value(s) 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.) in a scalar or array 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. Syntax CDF_EPOCH, Epoch, Year [, Month, Day, Hour, Minute, Second, Milli [, /BREAKDOWN_EPOCH] [, /COMPUTE_EPOCH] Arguments Epoch The Epoch value(s) to be broken down, or a named variable into which the computed epoch value(s) will be placed. An Epoch value is the number of milliseconds since 01-Jan-0000 00:00:00.000. This field can be a scalar or array of values when to be broken down into date/time components. 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 CDF epochs into date/times and vice versa, you should only use the CDF_EPOCH16 routine with either the BREAKDOWN_EPOCH or COMPUTE_EPOCH keyword. Year The year(s) (such as 1992) or a named variable. Month The month(s) (1-12) or a named variable. You can also set the Month argument equal to zero, in which case the Day argument can take on any value between 1-366; this number is interpreted as the "Day of the Year" rather than a "Day of the Month". Day The day(s) (1-31) or a named variable. If the Month argument is set equal to zero, Day can be set to any value between 1-366. Hour The hour(s) (0-23) or a named variable. Minute The minute(s) (0-59) or a named variable. Second The second(s) (0-59) or a named variable. Milli The millisecond(s) (0-999) or a named variable. Keywords BREAKDOWN_EPOCH If this keyword is set, Epoch is a value(s) which will broken down and the resulting Year(s), Month(s), Day(s), etc. are returned in the remaining parameters which must be named variables. COMPUTE_EPOCH If this keyword is set, Epoch is a named variable into which the epoch is placed and the other parameters are values which will be used to compute the epoch. Examples To compute a single epoch value of September 20, 2005 at 3:05:46:156 am: CDF_EPOCH, epoch, 2005, 9, 20, 3, 5, 46, 156, /COMPUTE_EPOCH To break down the given epoch value into standard date components: CDF_EPOCH, epoch, yr, mo, dy, hr, min, sec, milli, /BREAK To compute an array of epoch values from the following three dates: 20-Sep-2005 03:05:46:156, 20-Sep-2005 03:06:22:234, 20-Sep-2005 03:07:12:345: 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] CDF_EPOCH, epoch2, yy, mm, dd, hh, mn, ss, ms, /COMPUTE_EPOCH Since the year, month, day, hour fields are the same in this sample, alternatively, the above command can be written as: CDF_EPOCH, epoch2, 2005, 9, 20, 3, mn, ss, ms, /COMPUTE_EPOCH To break down the above vectorized epoch values into standard date components: CDF_EPOCH, epoch2, yr, mo, dy, hr, min, sec, milli, /BREAK All yr, mo, dy, hr, min, sec, milli fields will be in array form. Version History Introduced: CDF 3.4.0 See Also CDF_ENCODE_EPOCH, CDF_PARSE_EPOCH Please see IDL help for the definition. Please see IDL help for the definition. Please see IDL help for the definition. CDF_LEAPSECONDS_INFO -------------------- The CDF_LEAPSECONDS_INFO function returns a structure containing information about the leap seconds used by CDF. Syntax result = CDF_LEAPSECONDS_INFO () Return Value The returned structure has the form: { USE_FILE: 1, CDF_LEAPSECONDSTABLE:"...", $ LASTUPDATED:LONARR(...), LEAPSECONDS: DOUBLEARR(...)} Explanation of the Structure Tags Tag USE_FILE This field will contain a 1 if the leap seconds are read from a file. 0 means 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. CDF_LEAPSECONDSTABLE This field contains the value of environment variable: CDF_LEAPSECONDSTABLE, if it is defined. Its value is supposed to 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 An array of ints. This field 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 Examples: info = CDF_LEAPSECONDS_INFO() help, info, /struct print, info Version History Introduced: CDF 3.4.0 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. Syntax CDF_LIB_INFO [, COPYRIGHT =variable] [, INCREMENT=variable] [, RELEASE=variable] [, SUBINCREMENT=variable] [, VERSION=variable] [, LEAPSECONDLASTUPDATED=date] 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. 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. LEAPSEONDLASTUPDATED A named variable in which the date, in YYYYMMDD, of the last entry in the leap second table will be returned. This date can be used to verify if a valid leap second table is being used either through internally or externally. 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 6.3 uses CDF Library 3.1.1 Common Data Format (CDF) (C) Copyright 1990-2005 NASA/GSFC Space Physics Data Facility NASA/Goddard Space Flight Center Greenbelt, Maryland 20771 USA (Internet -- CDFSUPPORT@LISTSERV.GSFC.NASA.GOV) Version History See Also CDF_DOC CDF_PARSE_EPOCH16 ----------------- The CDF_PARSE_EPOCH16 function parses a single or an array of properly-formatted input string(s) into a single or an array of double complex value(s) properly formatted for use as a CDF_EPOCH16 variable. CDF_EPOCH16 variables may be encoded into a variety of formats using the CDF_ENCODE_EPOCH16 function or decomposed into date/time components using CDF_EPOCH16, /BREAKDOWN_EPOCH function. Syntax Result = CDF_PARSE_EPOCH16(Epoch_string) Return Value Returns a single or an array (<= 2D) of double-complex value(s) of the input string. Arguments Epoch_string A scalar or an array (<= 2D) formatted string that will be parsed into a double-complex value(s) suitable to be used as a CDF_EPOCH16 value(s). The format expected by CDF_PARSE_EPOCH16 is dd-mmm-yyyy hh:mm:ss.ccc.uuu.nnn.ppp where: dd is the day of the month, 1-31. mmm is the month, Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, or Dec. yyyy is the year, A.D. hh is the hour, 0-23. mm is the minute, 0-59. ss is the second, 0-60 if leap second. ccc is the millisecond, 0-999. uuu is the microsecond, 0-999. nnn is the nanosecond, 0-999. ppp is the picosecond, 0-999. Keywords None. Examples 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 Output TEST_STRING STRING = '04-Dec-1995 20:19:18.176' TEST_EPOCH DCOMPLEX = 6.2985328e+13 04-Dec-2005 20:19:18.176.214.648.000 2005 12 4 20 19 18 176 214 648 000 Version History Introduced: CDF 3.4.0 See Also CDF_ENCODE_EPOCH16, CDF_EPOCH16 CDF_PARSE_EPOCH --------------- The CDF_PARSE_EPOCH function parses a properly-formatted input string(s) into a single or an array of double value(s) properly formatted for use as a CDF_EPOCH variable. CDF_EPOCH variables may be encoded into a variety of formats using the CDF_ENCODE_EPOCH function or decomposed into date/time components using CDF_EPOCH,/BREAKDOWN_EPOCH function. Syntax Result = CDF_PARSE_EPOCH(Epoch_string) Return Value Returns a single or an array (<= 2D) double value(s) of the input string. Arguments Epoch_string A scalar or an array (<= 2D) of formatted string(s) that will be parsed into a single or array of double value(s) suitable to be used as a CDF_EPOCH value. The format expected by CDF_PARSE_EPOCH is dd-mmm-yyyy hh:mm:ss.ccc.uuu.nnn.ppp where: dd is the day of the month, 1-31. mmm is the month, Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, or Dec. yyyy is the year, A.D. hh is the hour, 0-23. mm is the minute, 0-59. ss is the second, 0-60 if leap second. ccc is the millisecond, 0-999. Keywords None. Examples test_string = '04-Dec-2005 20:19:18.176' test_epoch = CDF_PARSE_EPOCH(test_string) CDF_EPOCH,test_epoch, year, month, day, hour, min, sec, milli, $ /BREAKDOWN_EPOCH HELP, test_string, test_epoch PRINT, CDF_ENCODE_EPOCH(test_epoch) PRINT, year, month, day, hour, min, sec, milli IDL Output TEST_STRING STRING = '04-Dec-1995 20:19:18.176' TEST_EPOCH DOUBLE = 6.2985328e+13 04-Dec-2005 20:19:18.176 2005 12 4 20 19 18 176 Version History Introduced: CDF 3.4.0 See Also CDF_ENCODE_EPOCH, CDF_EPOCH CDF_PARSE_TT2000 ---------------- The CDF_PARSE_TT2000 function parses a single or an array of properly-formatted input string into a 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. Syntax Result = CDF_PARSE_TT2000(Epoch_string) Return Value Returns a single or an array (<= 2D) of 8-byte integer value(s) of the input string(s). Arguments Epoch_string A scalar or an array (<= 2D) formatted string(s) that will be parsed into a 8-byte value to be used as a CDF_TIME_TT2000 data type. The format can be one of the predefined formats. However, the default expected by CDF_PARSE_TT2000 is yyyy-mm-ddThh:mm:ss.cccuuunnn, a ISO 8601 form, where: yyyy is the year, A.D. mm is the month, 1-12. dd is the day of the month, 1-31. hh is the hour, 0-23. mm is the minute, 0-59. ss is the second, 0-59 (0-60 if leap second applicable). ccc is the millisecond, 0-999. uuu is the microsecond, 0-999. nnn is the nanosecond, 0-999. Keywords None. 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 = '1995-12-04T20:19:18.176214648' TEST_EPOCH LONG64 = 186999558176214648 2005-12-04T20:19:18.176214648 2005.000 12.000000 4.0000000 20.000000 19.000000 18.000000 176.00000 214.00000 648.00000 Version History Introduced: CDF 3.4.0 See Also CDF_ENCODE_TT2000, CDF_TT2000 CDF_SET_CDF27_BACKWARD_COMPATIBLE ---------------------------------- The CDF_SET_CDF27_BACKWARD_COMPATIBLE function allows users to create a CDF file that can be read by IDL 6.2 (or earlier IDL versions) or CDF 2.7.2 (or earlier CDF versions). By default, a CDF file created by IDL 6.3 (which uses CDF 3.1) or CDF 3.0 or a later release can't be read by CDF library that's older than 3.0 (e.g. IDL 6.2, CDF 2.7.x, 2.6.x, 2.5.x, etc.). This new routine is for users who wish to create and share CDF files with colleagues who access CDF files using IDL 6.2 (or earlier version) or a CDF library that's older than 3.0 (e.g. 2.7.x, 2.6.x, 2.5.x, etc.) This routine must be called prior to calling the CDF_CREATE routine. Note that up until CDF 2.7.2, the maximum CDF file size was 2 Gbytes and this limitation was lifted in CDF 3.0 with the use of 64-bit file offset. As a result, users who use a CDF library older than CDF 3.0 can't read CDF files that were produced by CDF 3.0 or a later release. But CDF 3.0 or a later release can read files that were generated with any of the previous CDF releases. Syntax CDF_SET_CDF27_BACKWARD_COMPATIBLE, /YES | /NO Keywords YES Create a CDF file that can be read by IDL 6.2 (or earlier IDL versions) or CDF 2.7.2 (or earlier CDF releases). If this option is set, the maximum file size is 2 Gbytes. NO This is the default when a CDF file is created. 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 Version History Introduced: IDL 6.3 CDF_SET_MD5CHECKSUM ------------------- The CDF_SET_MD5CHECKSUM procedure allows users to optionally use MD5 checksum method for a CDF file that can ensure the data integrity can be preserved. Syntax CDF_SET_MD5CHECKSUM, id, [/REMOVE] Keywords REMOVE Remove a previously-created checksum from the CDF file. Examples Use the following command to create a CDF file that will use MD5 checksum method to ensure the data integrity. id = CDF_CREATE('myfile.cdf') CDF_SET_MD5CHECKSUM, id, /YES CDF_CLOSE, id Version History Introduced: IDL 6.3 CDF_SET_VALIDATE ---------------------------------- The CDF_SET_VALIDATE function allows users to set whether to validate the data values in a CDF file when it is opened. The default is to perform the data check. The main purpose of the data checking is to address any security concern, e.g., buffer overflow, from the CDF caused by compromised CDF files. Some overheads are accrued from the data validation. Turn the data checking off if the files being processed are considered clean and compromise-free. Syntax CDF_SET_VALIDATE [,/YES|/NO] Keywords NO Bypass the data checking when the CDF files are opened. YES This is the default when CDF files are opened. Examples Use the following command to instruct CDF not to perform data validation when files are opened. CDF_SET_VALIDATE, /NO id = CDF_OPEN('myfile.cdf') CDF_CLOSE, id Version History Introduced: IDL 7.* CDF_TT2000 ---------- The CDF_TT2000 procedure computes or breaks down a single or an array of CDF_TIME_TT2000 value(s) in a CDF file. When computing an epoch, any missing value is considered to be zero. If you supply a scalar or an array values for the TT2000 argument and set the BREAKDOWN_EPOCH keyword, CDF_EPOCH will break down the epoch value(s) into 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.) in a scalar or array and set the COMPUTE_EPOCH keyword, CDF_EPOCH will compute the epoch and place the value(s) in the named variable supplied as the Epoch parameter. Note: You must set either the BREAKDOWN_EPOCH or COMPUTE_EPOCH keyword. Syntax CDF_TT2000, Epoch, Year, Month, Day [, Hour, Minute, Second, Milli, Micro, Nano] [, /BREAKDOWN_EPOCH] [, /COMPUTE_EPOCH] [, /TOINTEGER] Arguments Epoch A scalar or an array (<= 2D) of Epoch value(s) to be broken down, or a named variable into which the computed epoch will be placed. A TT2000 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(s) (such as 1992) or a named variable. Month The month(s) (1-12) or a named variable. You can also set the Month argument equal to zero, in which case the Day argument can take on any value between 1-366; this number is interpreted as the "Day of the Year" rather than a "Day of the Month". Day The day(s) (1-31) or a named variable. If the Month argument is set equal to zero, Day can be set to any value between 1-366. Hour The hour(s) (0-23) or a named variable. Minute The minute(s) (0-59) or a named variable. Second The second(s) (0-59 or 0-60 if leap second) or a named variable. Milli The millisecond(s) (0-999) or a named variable. Micro The microsecond(s) (0-999) or a named variable. Nano The nanosecond(s) (0-999) or a named variable. Note: For the entered date/time components to compute the epoch, only the last component is allowed to be fractional. Otherwise, a message of illegal value is returned. When an epoch is broken down into date/time components, all are in double form by default. Keywords BREAKDOWN_EPOCH If this keyword is set, Epoch is a value which will broken down and the resulting Year, Month, Day, etc. are returned in the remaining parameters which must be named variables. COMPUTE_EPOCH If this keyword is set, Epoch is a named variable into which the epoch is placed and the other parameters are values which will be used to compute the epoch. TOINTEGER This keyword is applicable 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. 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, alternatively, the above command can 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. Version History Introduced: CDF 3.4.0 See Also CDF_ENCODE_TT2000, CDF_PARSE_TT2000 CDF_VARCREATE ------------- The CDF_VARCREATE function creates a new variable in a Common Data Format file. CDF's "variable" is a generic name or an object that represents data where data can be 0-dimensional (scalar data) or multi-dimensional (up to 10-dimension), and it does not have any scientific context associated it. For example, a variable can be data representing an independent variable, a dependent variable, time and date value, or whatever data might be (e.g. image, XML file, etc.). In other words, the variable doesn't contain any hidden meanings other than the data itself. One may describe one variable's relationship with other variable(s) through CDF's "attributes". There are two types of variables (rVariable and zVariable) and they can coexist in the same CDF file. Every rVariable in a CDF must have the same number of dimensions and dimension sizes, whereas each zVariable has its own dimension and dimension size. Suppose there are 2 rVariables (v1, v2) in a CDF. Let's say v2 is defined as 2:[20,10] - 2-dimensional array with its size of 20 x 10 (20 rows and 10 columns). Then v1 MUST be defined as 2:[20,10] albeit it only needs 1:[8] (since it is a rVariable). But if this model is implemented using zVariables, then v1 and v2 can be defined as 1:[20,10] and 1:[8] instead of 1:[20,10] and 1:[20,10]. As you can see above, since all the rVariables must have the same dimensions and dimension sizes, there'll be a lot of disk space wasted if a few variables need big arrays and many variables need small arrays. So why would you want to use rVariables over zVariables? There's no reason to use rVariables at all (since zVariables are much more efficient) if you are creating a new CDF file. But if you are analyzing data files that were created with early CDF releases or contain rVariables for some reason, you'll need to use rVariables. One may wonder why there are rVariables and zVariables, not just zVariables. When CDF was first introduced in early 90's, only rVariables were available. The inefficiencies with rVariables were quickly realized and addressed with the introduction of zVariables in later CDF releases. 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_UCHAR CDF_INT1 CDF_UINT1 CDF_INT8 CDF_INT2 CDF_UINT2 CDF_TIME_TT2000 CDF_INT4 CDF_UINT4 CDF_FLOAT CDF_REAL4 CDF_DOUBLE CDF_REAL8 CDF_EPOCH CDF_LONG_EPOCH If no type is specified, CDF_FLOAT is assumed. CDF_LONG_EPOCH represents the CDF_EPOCH16 data type. CDF_TIME_TT2000, nano-seconds since J2000 with leap seconds, is a new CDF epoch type. It uses the same IDL data type, IDL_TYP_LONG64, as CDF_INT8. Make sure to use "/cdf_epoch" keyword for cdf_attput call if an attribute entry of CDF_TIME_TT2000 is intended for the output. 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 ensure that variable data is stored contiguously in the CDF file. For discussion about allocating records, see section 2.3.12 ("Records") of the CDF User's Guide. DIMENSIONS Set this keyword to create a new zVariable with the specified dimensions. For example: id = CDF_CREATE("cdffile.cdf", [100] ) zid = CDF_VARCREATE(id, "Zvar", [1,1,1], DIM=[10,20,30], /ZVARIABLE) 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 If this keyword is not set, a variable is assumed to be a rVariable. rVariable is a subset of zVariable, and it's highly recommended that variable should always be created as zVariable since it's much more efficient than rVariables. A variable is assumed to be a zVariable if its dimensions are specified by the DIMENSIONS keyword. If the dimension is not specified in the DIMENSIONS keyword, the variable is assumed to be a scalar (0-dimension). For example: id = CDF_CREATE("cdffile.cdf") zid1 = CDF_VARCREATE(id, "Zvar1", /ZVARIABLE) zid2 = CDF_VARCREATE(id, "Zvar2", ['VARY','VARY'], DIM=[3,10], /CDF_INT2, /ZVARIABLE) Examples Example 1 In this example, we create a CDF file to record the data retrieved from an array of temperature and salinity detectors. There is a 3 x 4 array of detectors at two depths, 10.0 meters and 20.2 meters: id = CDF_CREATE("temp_salinity.cdf", [3,4], /NETWORK_ENCODING, $ /SUN_DECODING, /CLOBBER) temp_id =CDF_VARCREATE(id, "Temperature", ['Vary', 'Vary'], $ /REC_VARY,/CDF_FLOAT) depth_id = CDF_VARCREATE(id, "Depth", [0,0], /REC_VARY, /CDF_FLOAT, $ /ZVARIABLE) sal_id = CDF_VARCREATE(id, "Salinity", [1,1], /REC_VARY, /CDF_DOUBLE, /ZVARIABLE) ; Create and fill the UNITS attribute: units_att = CDF_ATTCREATE(id, 'UNITS', /VARIABLE) CDF_ATTPUT, id, 'UNITS', 'Depth', 'Meters' CDF_ATTPUT, id, 'UNITS', temp_id, 'Kelvin' CDF_ATTPUT, id, units_att, sal_id, 'Percent' ; Create and write some fictitious data: data1 = 20.0 + FINDGEN(3,4) CDF_VARPUT, id, varid, data1 ; IDL will handle the type conversion, CDF will set all values ; of this record to a depth of 10.0. CDF_VARPUT, id, depth_id, '10.0' CDF_VARPUT, id, depth_id, 20.2,rec_start=1 ; Set the second depth. CDF_VARPUT, id, sal_id, DINDGEN(3,4)/10.0 ; Make more fictitious data. ; Demonstrate the non-variance of depth by retrieving the ; values. On the first pass, use CDF_VARGET1 to retrieve ; single values: CDF_VARGET1, id, depth_id, pth_0 ; Get single values. CDF_VARGET1, id, depth_id, depth_1, REC_START=1 ; Get single values. HELP, depth_0, depth_1 ; Now retrieve the full depth records: CDF_VARGET, id, depth_id, depth, REC_COUNT=2 ;Examine the depth variable: HELP, depth PRINT, depth IDL Output DEPTH_0 FLOAT = 10.0000 DEPTH_1 FLOAT = 20.2000 DEPTH FLOAT = Array(3, 4, 2) 10.0000 10.0000 10.0000 10.0000 10.0000 10.0000 10.0000 10.0000 10.0000 10.0000 10.0000 10.0000 20.2000 20.2000 20.2000 20.2000 20.2000 20.2000 20.2000 20.2000 20.2000 20.2000 20.2000 20.2000 Example 2 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: 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)) CDF_CLOSE, id ; Close the CDF file. Version History Introduced: Pre 4.0 Please see IDL help for the definition. Please see IDL help for the definition. 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{data in CDF file must be type CDF_CHAR or CDF_UCHAR}] [, /ZVARIABLE] [, /TO_COLUMN_MAJOR] 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 numberi 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. 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. 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. TO_COLUMN_MAJOR Set this keyword to convert full record data read from a multi-dimensional (>1) variable in a row-major CDF to a column-major form. The returned data keep the same dimensionality as the variable's. With this keyword, the dimensions defined at variable's meta-data: DEPEND_1, DEPEND_2, etc, in an ISTP compilant CDF will match to the returned data. This keyword is only applicable to reading full variable record(s). 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 Comments This page has no comments yet. Be the first one! CDF_VARINQ The CDF_VARINQ function returns a structure containing information about the specified variable in a Common Data Format file. Syntax Result = CDF_VARINQ( Id , Va r i a b l e [, /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 ini 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 thei 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. Examples See the example for “CDF_VARGET” Please see IDL help for the definition. Please see IDL help for the definition. Please see IDL help for the definition.