gsfc.nssdc.cdf
Class CDF

java.lang.Object
  extended by gsfc.nssdc.cdf.CDF
All Implemented Interfaces:
CDFConstants, CDFObject

public class CDF
extends java.lang.Object
implements CDFObject, CDFConstants

The CDF class is the main class used to interact with a CDF file.

Notes:

CDF dataTypeJava dataTypeRead/Write
CDF_BYTEjava.lang.ByteY/Y
CDF_INT1java.lang.ByteY/Y
CDF_UINT1java.lang.ShortY/Y
CDF_INT2java.lang.ShortY/Y
CDF_UINT2java.lang.IntegerY/Y
CDF_INT4java.lang.IntegerY/Y
CDF_UINT4java.lang.LongY/Y
CDF_FLOATjava.lang.FloatY/Y
CDF_REAL4java.lang.FloatY/Y
CDF_DOUBLEjava.lang.DoubleY/Y
CDF_REAL8java.lang.DoubleY/Y
CDF_CHARjava.lang.StringY/Y
CDF_UCHARjava.lang.StringY/Y
Supported dataTypes and their mappings

Version:
1.0, 2.0 03/18/05 Selection of current attribute is done as part of operations passed to JNI. JNI call is synchronized so only one process is allowed in a JVM, due to multi-thread safety. The select method will never be called. Sync'd the CDF (id) for every JNI calls.
See Also:
Attribute, CDFException, Variable

Field Summary
 
Fields inherited from interface gsfc.nssdc.cdf.CDFConstants
AHUFF_COMPRESSION, ALPHAOSF1_DECODING, ALPHAOSF1_ENCODING, ALPHAVMSd_DECODING, ALPHAVMSd_ENCODING, ALPHAVMSg_DECODING, ALPHAVMSg_ENCODING, ALPHAVMSi_DECODING, ALPHAVMSi_ENCODING, ATTR_, ATTR_EXISTENCE_, ATTR_EXISTS, ATTR_MAXgENTRY_, ATTR_MAXrENTRY_, ATTR_MAXzENTRY_, ATTR_NAME_, ATTR_NAME_TRUNC, ATTR_NUMBER_, ATTR_NUMgENTRIES_, ATTR_NUMrENTRIES_, ATTR_NUMzENTRIES_, ATTR_SCOPE_, BACKWARD_, BACKWARDFILEoff, BACKWARDFILEon, BAD_ALLOCATE_RECS, BAD_ARGUMENT, BAD_ATTR_NAME, BAD_ATTR_NUM, BAD_BLOCKING_FACTOR, BAD_CACHE_SIZE, BAD_CDF_EXTENSION, BAD_CDF_ID, BAD_CDF_NAME, BAD_CDFSTATUS, BAD_CHECKSUM, BAD_COMPRESSION_PARM, BAD_DATA_TYPE, BAD_DECODING, BAD_DIM_COUNT, BAD_DIM_INDEX, BAD_DIM_INTERVAL, BAD_DIM_SIZE, BAD_ENCODING, BAD_ENTRY_NUM, BAD_FNC_OR_ITEM, BAD_FORMAT, BAD_INITIAL_RECS, BAD_MAJORITY, BAD_MALLOC, BAD_NEGtoPOSfp0_MODE, BAD_NUM_DIMS, BAD_NUM_ELEMS, BAD_NUM_VARS, BAD_READONLY_MODE, BAD_REC_COUNT, BAD_REC_INTERVAL, BAD_REC_NUM, BAD_SCOPE, BAD_SCRATCH_DIR, BAD_SPARSEARRAYS_PARM, BAD_VAR_NAME, BAD_VAR_NUM, BAD_zMODE, CANNOT_ALLOCATE_RECORDS, CANNOT_CHANGE, CANNOT_COMPRESS, CANNOT_COPY, CANNOT_SPARSEARRAYS, CANNOT_SPARSERECORDS, CDF_, CDF_ACCESS_, CDF_ATTR_NAME_LEN, CDF_BYTE, CDF_CACHESIZE_, CDF_CHAR, CDF_CHECKSUM_, CDF_CLOSE_ERROR, CDF_COMPRESSION_, CDF_COPYRIGHT_, CDF_COPYRIGHT_LEN, CDF_CREATE_ERROR, CDF_DECODING_, CDF_DELETE_ERROR, CDF_DOUBLE, CDF_ENCODING_, CDF_EPOCH, CDF_EPOCH16, CDF_EXISTS, CDF_FLOAT, CDF_FORMAT_, CDF_INCREMENT_, CDF_INFO_, CDF_INT1, CDF_INT2, CDF_INT4, CDF_INTERNAL_ERROR, CDF_MAJORITY_, CDF_MAX_DIMS, CDF_MAX_PARMS, CDF_MIN_DIMS, CDF_NAME_, CDF_NAME_TRUNC, CDF_NEGtoPOSfp0_MODE_, CDF_NUMATTRS_, CDF_NUMgATTRS_, CDF_NUMrVARS_, CDF_NUMvATTRS_, CDF_NUMzVARS_, CDF_OK, CDF_OPEN_ERROR, CDF_PATHNAME_LEN, CDF_READ_ERROR, CDF_READONLY_MODE_, CDF_REAL4, CDF_REAL8, CDF_RELEASE_, CDF_SAVE_ERROR, CDF_SCRATCHDIR_, CDF_STATUS_, CDF_STATUSTEXT_LEN, CDF_UCHAR, CDF_UINT1, CDF_UINT2, CDF_UINT4, CDF_VAR_NAME_LEN, CDF_VERSION_, CDF_WARN, CDF_WRITE_ERROR, CDF_zMODE_, CDFwithSTATS_, CHECKSUM_, CHECKSUM_ERROR, CHECKSUM_NOT_ALLOWED, CLOSE_, COLUMN_MAJOR, COMPRESS_CACHESIZE_, COMPRESSION_ERROR, CONFIRM_, CORRUPTED_V2_CDF, CORRUPTED_V3_CDF, CREATE_, CURgENTRY_EXISTENCE_, CURrENTRY_EXISTENCE_, CURzENTRY_EXISTENCE_, DATATYPE_MISMATCH, DATATYPE_SIZE_, DECOMPRESSION_ERROR, DECSTATION_DECODING, DECSTATION_ENCODING, DEFAULT_BYTE_PADVALUE, DEFAULT_CHAR_PADVALUE, DEFAULT_DOUBLE_PADVALUE, DEFAULT_EPOCH_PADVALUE, DEFAULT_FLOAT_PADVALUE, DEFAULT_INT1_PADVALUE, DEFAULT_INT2_PADVALUE, DEFAULT_INT4_PADVALUE, DEFAULT_REAL4_PADVALUE, DEFAULT_REAL8_PADVALUE, DEFAULT_UCHAR_PADVALUE, DEFAULT_UINT1_PADVALUE, DEFAULT_UINT2_PADVALUE, DEFAULT_UINT4_PADVALUE, DELETE_, DID_NOT_COMPRESS, EMPTY_COMPRESSED_CDF, END_OF_VAR, EPOCH_STRING_LEN, EPOCH_STRING_LEN_EXTEND, EPOCH1_STRING_LEN, EPOCH1_STRING_LEN_EXTEND, EPOCH2_STRING_LEN, EPOCH2_STRING_LEN_EXTEND, EPOCH3_STRING_LEN, EPOCH3_STRING_LEN_EXTEND, EPOCHx_FORMAT_MAX, EPOCHx_STRING_MAX, FORCED_PARAMETER, gENTRY_, gENTRY_DATA_, gENTRY_DATASPEC_, gENTRY_DATATYPE_, gENTRY_EXISTENCE_, gENTRY_NUMELEMS_, GET_, GETCDFCHECKSUM_, GETCDFFILEBACKWARD_, GLOBAL_SCOPE, GZIP_COMPRESSION, HOST_DECODING, HOST_ENCODING, HP_DECODING, HP_ENCODING, HUFF_COMPRESSION, IBM_PC_OVERFLOW, IBMPC_DECODING, IBMPC_ENCODING, IBMRS_DECODING, IBMRS_ENCODING, ILLEGAL_EPOCH_FIELD, ILLEGAL_EPOCH_VALUE, ILLEGAL_FOR_SCOPE, ILLEGAL_IN_zMODE, ILLEGAL_ON_V1_CDF, LIB_COPYRIGHT_, LIB_INCREMENT_, LIB_RELEASE_, LIB_subINCREMENT_, LIB_VERSION_, MAC_DECODING, MAC_ENCODING, MD5_CHECKSUM, MULTI_FILE, MULTI_FILE_FORMAT, NA_FOR_VARIABLE, NEGATIVE_FP_ZERO, NEGtoPOSfp0off, NEGtoPOSfp0on, NETWORK_DECODING, NETWORK_ENCODING, NeXT_DECODING, NeXT_ENCODING, NO_ATTR_SELECTED, NO_CDF_SELECTED, NO_CHECKSUM, NO_COMPRESSION, NO_DELETE_ACCESS, NO_ENTRY_SELECTED, NO_MORE_ACCESS, NO_PADVALUE_SPECIFIED, NO_SPARSEARRAYS, NO_SPARSERECORDS, NO_STATUS_SELECTED, NO_SUCH_ATTR, NO_SUCH_CDF, NO_SUCH_ENTRY, NO_SUCH_RECORD, NO_SUCH_VAR, NO_VAR_SELECTED, NO_VARS_IN_CDF, NO_WRITE_ACCESS, NONE_CHECKSUM, NOT_A_CDF, NOT_A_CDF_OR_NOT_SUPPORTED, NOVARY, NULL_, OPEN_, OPTIMAL_ENCODING_TREES, OTHER_CHECKSUM, PAD_SPARSERECORDS, PRECEEDING_RECORDS_ALLOCATED, PREV_SPARSERECORDS, PUT_, READ_ONLY_DISTRIBUTION, READ_ONLY_MODE, READONLYoff, READONLYon, rENTRY_, rENTRY_DATA_, rENTRY_DATASPEC_, rENTRY_DATATYPE_, rENTRY_EXISTENCE_, rENTRY_NAME_, rENTRY_NUMELEMS_, RLE_COMPRESSION, RLE_OF_ZEROs, ROW_MAJOR, rVAR_, rVAR_ALLOCATEBLOCK_, rVAR_ALLOCATEDFROM_, rVAR_ALLOCATEDTO_, rVAR_ALLOCATERECS_, rVAR_BLOCKINGFACTOR_, rVAR_CACHESIZE_, rVAR_COMPRESSION_, rVAR_DATA_, rVAR_DATASPEC_, rVAR_DATATYPE_, rVAR_DIMVARYS_, rVAR_EXISTENCE_, rVAR_HYPERDATA_, rVAR_INITIALRECS_, rVAR_MAXallocREC_, rVAR_MAXREC_, rVAR_NAME_, rVAR_nINDEXENTRIES_, rVAR_nINDEXLEVELS_, rVAR_nINDEXRECORDS_, rVAR_NUMallocRECS_, rVAR_NUMBER_, rVAR_NUMELEMS_, rVAR_NUMRECS_, rVAR_PADVALUE_, rVAR_RECORDS_, rVAR_RECVARY_, rVAR_RESERVEPERCENT_, rVAR_SEQDATA_, rVAR_SEQPOS_, rVAR_SPARSEARRAYS_, rVAR_SPARSERECORDS_, rVARs_CACHESIZE_, rVARs_DIMCOUNTS_, rVARs_DIMINDICES_, rVARs_DIMINTERVALS_, rVARs_DIMSIZES_, rVARs_MAXREC_, rVARs_NUMDIMS_, rVARs_RECCOUNT_, rVARs_RECDATA_, rVARs_RECINTERVAL_, rVARs_RECNUMBER_, SAVE_, SCRATCH_CREATE_ERROR, SCRATCH_DELETE_ERROR, SCRATCH_READ_ERROR, SCRATCH_WRITE_ERROR, SELECT_, SGi_DECODING, SGi_ENCODING, SINGLE_FILE, SINGLE_FILE_FORMAT, SOME_ALREADY_ALLOCATED, STAGE_CACHESIZE_, STATUS_TEXT_, SUN_DECODING, SUN_ENCODING, TOO_MANY_PARMS, TOO_MANY_VARS, UNKNOWN_COMPRESSION, UNKNOWN_SPARSENESS, UNSUPPORTED_OPERATION, VAR_ALREADY_CLOSED, VAR_CLOSE_ERROR, VAR_CREATE_ERROR, VAR_DELETE_ERROR, VAR_EXISTS, VAR_NAME_TRUNC, VAR_OPEN_ERROR, VAR_READ_ERROR, VAR_SAVE_ERROR, VAR_WRITE_ERROR, VARIABLE_SCOPE, VARY, VAX_DECODING, VAX_ENCODING, VIRTUAL_RECORD_DATA, zENTRY_, zENTRY_DATA_, zENTRY_DATASPEC_, zENTRY_DATATYPE_, zENTRY_EXISTENCE_, zENTRY_NAME_, zENTRY_NUMELEMS_, zMODEoff, zMODEon1, zMODEon2, zVAR_, zVAR_ALLOCATEBLOCK_, zVAR_ALLOCATEDFROM_, zVAR_ALLOCATEDTO_, zVAR_ALLOCATERECS_, zVAR_BLOCKINGFACTOR_, zVAR_CACHESIZE_, zVAR_COMPRESSION_, zVAR_DATA_, zVAR_DATASPEC_, zVAR_DATATYPE_, zVAR_DIMCOUNTS_, zVAR_DIMINDICES_, zVAR_DIMINTERVALS_, zVAR_DIMSIZES_, zVAR_DIMVARYS_, zVAR_EXISTENCE_, zVAR_HYPERDATA_, zVAR_INITIALRECS_, zVAR_MAXallocREC_, zVAR_MAXREC_, zVAR_NAME_, zVAR_nINDEXENTRIES_, zVAR_nINDEXLEVELS_, zVAR_nINDEXRECORDS_, zVAR_NUMallocRECS_, zVAR_NUMBER_, zVAR_NUMDIMS_, zVAR_NUMELEMS_, zVAR_NUMRECS_, zVAR_PADVALUE_, zVAR_RECCOUNT_, zVAR_RECINTERVAL_, zVAR_RECNUMBER_, zVAR_RECORDS_, zVAR_RECVARY_, zVAR_RESERVEPERCENT_, zVAR_SEQDATA_, zVAR_SEQPOS_, zVAR_SPARSEARRAYS_, zVAR_SPARSERECORDS_, zVARs_CACHESIZE_, zVARs_MAXREC_, zVARs_RECDATA_, zVARs_RECNUMBER_
 
Method Summary
 void close()
          Closes this CDF file.
 long confirmCDFCacheSize()
          Gets the CDF cache size (the number of 512-byte cache buffers) set for this CDF.
 long confirmCompressCacheSize()
          Gets the number of 512-byte cache buffers being used for the compression scratch file (for the current CDF).
 long confirmDecoding()
          Gets the CDF decoding method defined for this CDF.
 long confirmNegtoPosfp0()
          Gets the -0.0 to 0.0 translation flag set for this CDF.
 long confirmReadOnlyMode()
          Gets the value of the read-only mode flag set for this CDF file.
 long confirmStageCacheSize()
          Gets the number of 512-byte cache buffers defined for the staging scratch file.
 long confirmzMode()
          Gets the zMode set for this CDF.
static CDF create(java.lang.String path)
          Creates a CDF file in the current directory.
static CDF create(java.lang.String path, int flag)
          Deprecated. Use setFileBackward(long) method to set the file backward flag and create(String) to create file instead.
 void delete()
          Deletes this CDF file.
 void finalize()
          Do the necessary cleanup when garbage collector reaps it.
 Attribute getAttribute(long attrNum)
          Gets the attribute for the given attribute number.
 Attribute getAttribute(java.lang.String attrName)
          Gets the attribute for the given attribute name.
 long getAttributeID(java.lang.String attrName)
          Gets the id of the given attribute.
 java.util.Vector getAttributes()
          Gets all the global and variable attributes defined for this CDF.
 long getChecksum()
          Gets the checksum method, if any, applied to the CDF.
static long getChecksumEnvVar()
          Gets the indication of the CDF_CHECKSUM environment variable.
 java.lang.String getCompression()
          Gets the string representation of the compression type and parameters defined for this CDF.
 long[] getCompressionParms()
          Gets the compression parameters set for this CDF.
 long getCompressionPct()
          Gets the compression percentage set for this CDF.
 long getCompressionType()
          Gets the compression type set for this CDF.
 java.lang.String getCopyright()
          Gets the CDF copyright statement for this CDF.
 CDFDelegate getDelegate()
          This is a placeholder for future expansions/extensions.
 long getEncoding()
          Gets the encoding method defined for this CDF.
static boolean getFileBackward()
          Gets the file backward flag.
static int getFileBackwardEnvVar()
          Gets the indication of the CDF_FILEBACKWARD environment variable.
 long getFormat()
          Gets the CDF format defined for this CDF.
 java.util.Vector getGlobalAttributes()
          Gets the global attributes defined for this CDF.
 long getID()
          Gets the id of this CDF file.
static java.lang.String getLibraryCopyright()
          Retrieve library copyright information associated with the CDF library.
static java.lang.String getLibraryVersion()
          Retrieve library version/release/increment/sub_increment information associated with the CDF library.
 long getMajority()
          Gets the variable majority defined for this CDF.
 java.lang.String getName()
          Gets the name of this CDF.
 long getNumAttrs()
          Gets the total number of global and variable attributes in this CDF.
 long getNumGattrs()
          Gets the number of global attributes in this CDF.
 long getNumRvars()
          Gets the number of r variables.
 long getNumVars()
          Gets the number of Z variables defined for this CDF.
 long getNumVattrs()
          Gets the number of variable attributes in this CDF.
 long getNumZvars()
          Gets the number of z variables in this CDF file.
 java.util.Vector getOrphanAttributes()
          Gets the variable attributes defined for this CDF that are not associated with any variables.
 java.util.Vector getRecord(long recNum, long[] varIDs)
          Retrieves a logical record that consists of single variable record(s) from an arbitrary number of CDF variables.
 java.util.Vector getRecord(long recNum, long[] varIDs, long[] status)
          Retrieves a logical record that consists of single variable record(s) from an arbitrary number of CDF variables.
 java.util.Vector getRecord(long recNum, java.lang.String[] strVars)
          Retrieves a logical record that consists of single variable record(s) from an arbitrary number of CDF variables.
 java.util.Vector getRecord(long recNum, java.lang.String[] strVars, long[] status)
          Retrieves a logical record that consists of single variable record(s) from an arbitrary number of CDF variables.
 long getStatus()
          Gets the status of the most recent CDF JNI/library function call.
static java.lang.String getStatusText(long statusCode)
          Gets the status text of the most recent CDF JNI/library function call.
 Variable getVariable(long varNum)
          Gets the variable object for the given variable number.
 Variable getVariable(java.lang.String varName)
          Gets the variable object for the given variable name.
 java.util.Vector getVariableAttributes()
          Gets the variable attributes defined for this CDF.
 long getVariableID(java.lang.String varName)
          Gets the ID of the given variable.
 java.util.Vector getVariables()
          Gets the z variables defined for this CDF.
 java.lang.String getVersion()
          Gets the CDF library version that was used to create this CDF (e.g. 2.6.7, etc.).
static CDF open(java.lang.String path)
          Open a CDF file for read/write, the default mode for opening a CDF.
static CDF open(java.lang.String path, long readOnly)
          Open a CDF file.
 void putRecord(long recNum, long[] varIDs, java.util.Vector myData)
          Writes a logical record that consists of single variable record(s) from an arbitrary number of CDF variables.
 void putRecord(long recNum, long[] varIDs, java.util.Vector myData, long[] status)
          Writes a logical record that consists of single variable record(s) from an arbitrary number of CDF variables.
 void putRecord(long recNum, java.lang.String[] strVars, java.util.Vector myData)
          Writes a logical record that consists of single variable record(s) from an arbitrary number of CDF variables.
 void putRecord(long recNum, java.lang.String[] strVars, java.util.Vector myData, long[] status)
          Writes a logical record that consists of single variable record(s) from an arbitrary number of CDF variables.
 void rename(java.lang.String path)
          Renames the current CDF.
 void save()
          Saves this CDF file without closing.
 void selectCDFCacheSize(long cacheSize)
          Defines the number of 512-byte cache buffers to be used for the dotCDF file (for the current CDF).
 void selectCompressCacheSize(long compressCacheSize)
          Sets the number of 512-byte cache buffers to be used for the compression scratch file (for the current CDF).
 void selectDecoding(long decoding)
          Defines the CDF decoding method to be used for this CDF.
 void selectNegtoPosfp0(long negtoPosfp0)
          Defines whether to translate -0.0 to 0.0 for reading or writing.
 void selectReadOnlyMode(long readOnly)
          Sets the desired read-only mode.
 void selectStageCacheSize(long stageCacheSize)
          Sets the number of 512-byte cache buffers to be used for the staging scratch file (for the current CDF).
 void setChecksum(long checksum)
          Specifies the checksum option applied to the CDF.
 void setCompression(long cType, long[] cParms)
          Sets the compression type and parameters for this CDF.
 void setDelegate(CDFDelegate delegate)
          This is a placeholder for future expansions/extensions.
 void setEncoding(long encoding)
          Defines the encoding method to be used for this CDF.
static void setFileBackward(long flag)
          Sets the file backward flag so that when a new CDF file is created, it will be created in either in the older V2.7 version or the current library version, i.e., V3.*.
 void setFormat(long format)
          Specifies the format of this CDF.
 void setInfoWarningOff()
          Sets the informational (status code > 0) or warning messages (status code between -1 and -2000) coming from the CDF JNI/library function off.
 void setInfoWarningOn()
          Sets the informational (status code > 0) or warning messages (status code between -1 and -2000) coming from the CDF JNI/library function on.
 void setMajority(long majority)
          Sets the variable majority for this CDF.
 java.lang.String toString()
          Gets the name of this CDF.
 long verifyChecksum()
          Verifies the data integrity of the CDF file from its checksum.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

create

public static CDF create(java.lang.String path)
                  throws CDFException
Creates a CDF file in the current directory. By default, a single-file CDF is created and it's the preferred format. However, if the user wants to create a multi-file CDF, its file format needs to be changed as following:

     CDF cdf = null;
     cdf = CDF.create("test");
     cdf.setFormat(MULTI_FILE); 
 
For the single-file format CDF, the above example would have created a single-file CDF called 'test.cdf'. See Chapter 1 of the CDF User's Guide for more information about the file format options. Notes:
The newly created file will be of the same version as the CDF library, as a V3.*. To create a backward file, i.e., V2.7, there are two options that can be used. Use the static method setFileBackward to set the backward flag. The following example will create backward file for test1.cdf and test2.cdf, but a V3.* file for test3.cdf.
     CDF cdf1, cdf2, cdf3;
     CDF.setFileBackward(BACKWARDFILEon);
     cdf1 = CDF.create("test1");
     cdf2 = CDF.create("test2");
     CDF.setFileBackward(BACKWARDFILEoff);
     cdf3 = CDF.create("test3");
 
Alternatively, use an environment variable to control the backward file creation. The environment variable CDF_FILEBACKWARD on Unix or Windows or CDF$FILEBACKWARD on Open/VMS is used. When it is set to TRUE, a V2.7 file(s) will be created automatically. In the following example, both test1.cdf and test2.cdf will be V2.7 if environment variable CDF_FILEBACKWARD (or CDF$FILEBACKWARD) is TRUE.
     CDF cdf1 = CDF.create("test1");
     CDF cdf2 = CDF.create("test2");
 

Parameters:
path - the full pathname of the CDF file to be created

Returns:
the newly created CDF file/object

Throws:
CDFException - if there was a problem creating a CDF file

create

public static CDF create(java.lang.String path,
                         int flag)
                  throws CDFException
Deprecated. Use setFileBackward(long) method to set the file backward flag and create(String) to create file instead.

Creates a CDF file in the current directory. By default, a single-file CDF is created and it's the preferred format. The following example will create a CDF file:

     CDF cdf = null;
     cdf = CDF.create("test", 0);
 
For the single-file format CDF, the above example would have created a single-file CDF called 'test.cdf'. The newly created file will be of the same version as the CDF library, To create a backward file, i.e., V2.7, use a differnt argument for the flag.
     CDF cdf;
     cdf = CDF.create("test", 1);
 

Parameters:
path - the full pathname of the CDF file to be created

flag the file backward indicator flag. Passed 0 if a file of current library version is to be created. Not 0 if a backward is to be created.

Returns:
the newly created CDF file/object

Throws:
CDFException - if there was a problem creating a CDF file

open

public static CDF open(java.lang.String path)
                throws CDFException
Open a CDF file for read/write, the default mode for opening a CDF. If the user wants only to read the file, the file must be opened in read-only mode as following:
     CDF cdf = CDF.open(fileName, READONLYon);
 
Note: Opening a file with read/write mode will cause the checksum signature to be recomputed every time the file is closed.

Parameters:
path - the full pathname of the CDF file to be opened

Returns:
the CDF object that represents the CDF file the user requested for opening

Throws:
CDFException - if there was a major problem opening a file Not always that a CDFException will be thrown. It is good pratice to check the status from this open method to see if some others problems, e.g., invalid checksum is being detected, may occur. Use something like the followings
              if (cdf.getStatus() != CDF_OK)
              {
                if (cdf.getStatus() == CHECKSUM_ERROR)
                  ......
              }
            
where cdf is the returned object from the open method. It is up to each individual to determine whether to continue to use a CDF file with an error like checksum.

open

public static CDF open(java.lang.String path,
                       long readOnly)
                throws CDFException
Open a CDF file. A CDF file can be opened in read-only or read/write mode. If a file is opened in read-only mode, the user can only read values out of the file. Any operation other than reading data will throw a CDFException. If the user wants to modify the contents of a file, the file must be opened in read/write mode as following:
     CDF cdf = CDF.open(fileName, READONLYoff);
 

Parameters:
path - the full pathname of the CDF file to be opened

readOnly - read-only flag that should be one the following:

  • READONLYon - opens the file in read only mode.
  • READONLYoff - opens the file in read/write mode

Returns:
the CDF object that represents the CDF file the user requested for opening

Throws:
CDFException - if there was a major problem opening a file Not always that a CDFException will be thrown. It is good pratice to check the status from this open method to see if some others problems, e.g., invalid checksum is being detected, may occur. Use something like the followings
              if (cdf.getStatus() != CDF_OK)
              {
                if (cdf.getStatus() == CHECKSUM_ERROR)
                  ......
              }
            
where cdf is the returned object from the open method. It is up to each individual to determine whether to continue to use a CDF file with an error like checksum.

getLibraryVersion

public static java.lang.String getLibraryVersion()
                                          throws CDFException
Retrieve library version/release/increment/sub_increment information associated with the CDF library.

Throws:
CDFException - If there was a problem retrieving the information associated with this CDF file

getLibraryCopyright

public static java.lang.String getLibraryCopyright()
                                            throws CDFException
Retrieve library copyright information associated with the CDF library.

Throws:
CDFException - If there was a problem retrieving the information associated with this CDF file

close

public void close()
           throws CDFException
Closes this CDF file. It is essential that a CDF that has been created or modified by an application be closed before the program exits. If the CDF is not closed, the file will be corrupted and unreadable. This is because the cache buffers maintained by the CDF library will not have been written to the CDF file(s).

The following example closes a CDF file:

     cdf.close();
 

Throws:
CDFException - if there was a problem closing the CDF file

getID

public long getID()
Gets the id of this CDF file.

Returns:
the id of this CDF file

getEncoding

public long getEncoding()
Gets the encoding method defined for this CDF.

Returns:
The encoding method defined for this CDF file. One of the encoding methods described in the setEncoding method is returned.

setEncoding

public void setEncoding(long encoding)
                 throws CDFException
Defines the encoding method to be used for this CDF. A CDF's data encoding affects how its attribute entry and variable data values are stored. By default, attribute entry and variable data values passed into the CDF library are always stored using the host machine's native encoding. For example, if a CDF file is created without specifying what encoding method should be should on a IBM PC, the IBMPC_ENCODING method is used. This method becomes useful if someone wants to create a CDF file that will be read on a machine that is different from the machine the CDF file was created. A CDF with any of the supported encodings may be read from and written to any supported computer. See section 2.2.8 of the CDF User's Guide for a detailed description of the encodings listed below.

Parameters:
encoding - the encoding method to be used for this CDF that should be one of the following:
  • HOST_ENCODING
  • NETWORK_ENCODING
  • SUN_ENCODING
  • VAX_ENCODING
  • DECSTATION_ENCODING
  • SGi_ENCODING
  • IBMPC_ENCODING
  • IBMRS_ENCODING
  • MAC_ENCODING
  • HP_ENCODING
  • NeXT_ENCODING
  • ALPHAOSF1_ENCODING
  • ALPHAVMSd_ENCODING
  • ALPHAVMSg_ENCODING
  • ALPHAVMSi_ENCODING

Throws:
CDFException - if there was a problem setting the requested encoding method

selectDecoding

public void selectDecoding(long decoding)
                    throws CDFException
Defines the CDF decoding method to be used for this CDF. A CDF's decoding affects how its attribute entry and variable data values are passed out to a calling application. The decoding for a CDF may be selected any number of times while the CDF is open. Selecting a decoding does not affect how the values are store in the CDF file(s) - only how the values are decoded by the CDF library.

Parameters:
decoding - the decoding method to be used for this CDF that should be one of the following:
  • HOST_DECODING - this is the default decoding
  • NETWORK_DECODING
  • SUN_DECODING
  • VAX_DECODING
  • DECSTATION_DECODING
  • SGi_DECODING
  • IBMPC_DECODING
  • IBMRS_DECODING
  • MAC_DECODING
  • HP_DECODING
  • NeXT_DECODING
  • ALPHAOSF1_DECODING
  • ALPHAVMSd_DECODING
  • ALPHAVMSg_DECODING
  • ALPHAVMSi_DECODING

Throws:
CDFException - if there was a problem selecting the requested decoding method

confirmDecoding

public long confirmDecoding()
                     throws CDFException
Gets the CDF decoding method defined for this CDF.

Returns:
The decoding method set for this CDF file. One of the decoding methods defined in the selectDecoding method is returned.

Throws:
CDFException - if there was a problem getting the decoding method set for this CDF file

selectCDFCacheSize

public void selectCDFCacheSize(long cacheSize)
                        throws CDFException
Defines the number of 512-byte cache buffers to be used for the dotCDF file (for the current CDF). The concepts Chapter in the CDF User's Guide describes the caching scheme used by the CDF library.

Parameters:
cacheSize - the number of 512-byte cache buffers

Throws:
CDFException - if there was a problem setting the CDF cache size

confirmCDFCacheSize

public long confirmCDFCacheSize()
                         throws CDFException
Gets the CDF cache size (the number of 512-byte cache buffers) set for this CDF.

Returns:
the number of 512-byte cache buffers set for this CDF

Throws:
CDFException - if there was a problem getting the CDF cache size

selectNegtoPosfp0

public void selectNegtoPosfp0(long negtoPosfp0)
                       throws CDFException
Defines whether to translate -0.0 to 0.0 for reading or writing. Negative floating-point zero (-0.0) is legal on computers that use IEEE 754 floating-point representation (e.g. most UNIX-based computers and the PC) but is illegal on VAXes and DEC alphas running OpenVMS operating system. If this mode disabled, a warning (NEGATIVE_FP_ZERO) is returned when -0.0 is read from a CDF (and the decoding is that of a VAX or DEC Alpha running OpenVMS) or written to a CDF (and the encoding is that of a VAX or DEC Alpha running i OpenVMS).

Parameters:
negtoPosfp0 - flag to translate -0.0 to 0.0 (NEGtoPOSfp0on = on, NEGtoPOSfp0off = off)

Throws:
CDFException - if there was a problem setting the -0.0 to 0.0 translation flag

confirmNegtoPosfp0

public long confirmNegtoPosfp0()
                        throws CDFException
Gets the -0.0 to 0.0 translation flag set for this CDF.

Returns:
flag to translate -0.0 to 0.0 (NEGtoPOSfp0on = on, NEGtoPOSfp0off = off)

Throws:
CDFException - if there was a problem getting the value of the -0.0 to 0.0 translation flag

getFormat

public long getFormat()
Gets the CDF format defined for this CDF.

Returns:
the format of this CDF (SINGLE_FILE = single-file CDF, MULTI_FILE = multi-file CDF)

setFormat

public void setFormat(long format)
               throws CDFException
Specifies the format of this CDF. A CDF's format can't be changed once any variables are created. See section 1.4 of the CDF User's Guide for more detailed information about the file format options.

Parameters:
format - the CDF file format to be used that should be one of the following:
  • SINGLE_FILE - This is the default. The CDF consists of only one file.
  • MULTI_FILE - The CDF consists of one header file for control and attribute data and one additional file for each variable in the CDF.

Throws:
CDFException - if there was a problem setting a file format

getVersion

public java.lang.String getVersion()
Gets the CDF library version that was used to create this CDF (e.g. 2.6.7, etc.).

Returns:
the CDF libray version number that was used to create this CDF

getMajority

public long getMajority()
Gets the variable majority defined for this CDF.

Returns:
the variable majority defined for this CDF (ROW_MAJOR = row major, COLUMN_MAJOR = column major)

setMajority

public void setMajority(long majority)
                 throws CDFException
Sets the variable majority for this CDF. The variable majority of a CDF describes how variable values within each variable array (record) are stored. Each variable in a CDF has the same majority.

Parameters:
majority - The majority to be used in storing data (ROW_MAJOR = row major, COLUMN_MAJOR = column major)

Throws:
CDFException - if a problem occurred in setting a majority

getNumAttrs

public long getNumAttrs()
Gets the total number of global and variable attributes in this CDF.

Returns:
the total number of global and variable attributes in this CDF

getNumGattrs

public long getNumGattrs()
Gets the number of global attributes in this CDF.

Returns:
the number of global attributes in this CDF file

getNumVattrs

public long getNumVattrs()
Gets the number of variable attributes in this CDF. Since r variables are not supported by the CDF Java APIs, the number of z variables is always returned.

Returns:
the number of variable attributes in this CDF file

getNumRvars

public long getNumRvars()
Gets the number of r variables. Zero is returned since r variables are not supported. Z variables can do everything r variables can do plus more.

Returns:
the number of r variables in this CDF file

getNumZvars

public long getNumZvars()
Gets the number of z variables in this CDF file.

Returns:
the number of z variables in this CDF file

getCopyright

public java.lang.String getCopyright()
Gets the CDF copyright statement for this CDF.

Returns:
the CDF copyright statement

selectReadOnlyMode

public void selectReadOnlyMode(long readOnly)
                        throws CDFException
Sets the desired read-only mode. See the description of the read-only flag defined in the open method in this class for details. Caveat: Arbitrary changing the read-only mode to READONLYon while doing writing/updating will cause a problem to the file if the checksum bit is turned on (as the checksum signature may not get updated and a warning for data integrity will be issued when the file is open later).

Parameters:
readOnly - read-only flag (READONLYon = on, READONLYoff = off)

Throws:
CDFException - if a problem occurred in setting a flag

confirmReadOnlyMode

public long confirmReadOnlyMode()
                         throws CDFException
Gets the value of the read-only mode flag set for this CDF file.

Returns:
read-only flag (READONLYon = on, READONLYoff = off)

Throws:
CDFException - if a problem occurred in getting the value of the read-only flag set for this CDF file

getCompressionType

public long getCompressionType()
Gets the compression type set for this CDF.

Returns:
the compression type set for this CDF - one of the following is returned:

  • NO_COMPRESSION - no compresssion
  • RLE_COMPRESSION - Run-length compression
  • HUFF_COMPRESSION - Huffman compression
  • AHUFF_COMPRESSION - Adaptive Huffman compression
  • GZIP_COMPRESSION - Gnu's "zip" compression

getCompressionPct

public long getCompressionPct()
Gets the compression percentage set for this CDF.

Returns:
the compression percentage set for this CDF.

getCompressionParms

public long[] getCompressionParms()
Gets the compression parameters set for this CDF. See the description of the setCompression method in this class for more information.

Returns:
the compression parameter set for this CDF

setCompression

public void setCompression(long cType,
                           long[] cParms)
                    throws CDFException
Sets the compression type and parameters for this CDF.

Parameters:
cType - the compression type to be applied to this CDF that should be one of the following:

  • NO_COMPRESSION - no compresssion
  • RLE_COMPRESSION - Run-length compression. Currently, only the run-length encoding of zeros is supported. The compression parameter must be set to RLE_OF_ZEROs.
  • HUFF_COMPRESSION - Huffman compression. Currently, only optimal encoding trees are supported. The compression parameter must be set to OPTIMAL_ENCODING_TREES.
  • AHUFF_COMPRESSION - Adaptive Huffman compression. Currently, only optimal encoding trees are supported. The compression parameter must be set to OPTIMAL_ENCODING_TREES.
  • GZIP_COMPRESSION - Gnu's "zip" compression. The compression parameter may range from 1 to 9. 1 provides the least compression and requires less execution time. 9 provides the most compression but requires the most execution time.

cParms - Compression parameter. There is only one parameter for all the compression methods described above.

Throws:
CDFException - if a problem occurred in setting the compression type and parameters

getCompression

public java.lang.String getCompression()
                                throws CDFException
Gets the string representation of the compression type and parameters defined for this CDF.

Returns:
the string representation of the compression type and parameters (e.g. GZIP.9, RLE.0, etc.) defined for this CDF

Throws:
CDFException - if a problem occurred in getting the compression type and parameters set for this CDF

confirmzMode

public long confirmzMode()
                  throws CDFException
Gets the zMode set for this CDF.

Returns:
'zMODEon2' is always returned since it is the only mode supported by the CDF Java APIs.

Throws:
CDFException - if a problem occurred in getting the zmode set for this CDF file

selectCompressCacheSize

public void selectCompressCacheSize(long compressCacheSize)
                             throws CDFException
Sets the number of 512-byte cache buffers to be used for the compression scratch file (for the current CDF). The Concepts Chapter in the CDF User's Guide describes the caching scheme used by the CDF library.

Parameters:
compressCacheSize - the number of 512-byte cache buffers to be used

Throws:
CDFException - if a problem occurs in setting the cache size

confirmCompressCacheSize

public long confirmCompressCacheSize()
                              throws CDFException
Gets the number of 512-byte cache buffers being used for the compression scratch file (for the current CDF).

Returns:
the number of 512-byte cache buffers being used
Throws:
CDFException - if a problem occurs in getting the cache size defined

selectStageCacheSize

public void selectStageCacheSize(long stageCacheSize)
                          throws CDFException
Sets the number of 512-byte cache buffers to be used for the staging scratch file (for the current CDF). The Concepts Chapter in the CDF User's Guide describes the caching scheme used by the CDF library.

Parameters:
stageCacheSize - the Number of cache buffers to be used
Throws:
CDFException - if a problem occurs in setting the cache size

confirmStageCacheSize

public long confirmStageCacheSize()
                           throws CDFException
Gets the number of 512-byte cache buffers defined for the staging scratch file.

Returns:
the number of 512-byte cache buffers defined for the staging scratch file
Throws:
CDFException - if a problem occurs in getting the number of cache buffers defined for the staging scratch file

getName

public java.lang.String getName()
Gets the name of this CDF.

Specified by:
getName in interface CDFObject
Returns:
the name of this CDF

rename

public void rename(java.lang.String path)
Renames the current CDF. It's here because CDF.java implements the CDFObject interface that defines three methods: rename, delete, getname. This method doesn't do anything now, but it will be refined to rename a single-CDF and multi-CDF files in the future.

Specified by:
rename in interface CDFObject
Parameters:
path - the new CDF name to be renamed to

delete

public void delete()
            throws CDFException
Deletes this CDF file.

Specified by:
delete in interface CDFObject
Throws:
CDFException - if a problem occurs in deleting this CDF file

save

public void save()
          throws CDFException
Saves this CDF file without closing. There are times the users will have to save the contents of a CDF file before some operations can be performed. For example, a CDF file must be saved first before records can be deleted properly for variables that are defined to have sparse and/or compressed records.

Throws:
CDFException - if there was a problem saving the contents of this CDF file

setFileBackward

public static void setFileBackward(long flag)
                            throws CDFException
Sets the file backward flag so that when a new CDF file is created, it will be created in either in the older V2.7 version or the current library version, i.e., V3.*. It only works for V3.* library. Setting this flag will overwrite environment varibale CDF_FILEBACKWARD (or CDF$FILEBACKWARD on OpenVMS) if it is set. All CDF files created after this static method call will be affected.

Parameters:
flag - The flag indicates whether to create a new CDF(s) in the backward version. BACKWARDFILEon means a backward file(s) is to be created and BACKWARDFILEoff means a V3.* file(s) is to be created.

Throws:
CDFException - if there was a problem setting the backward flag for this CDF file

getFileBackward

public static boolean getFileBackward()
Gets the file backward flag.

Returns:
The flag indicating whether the CDF file was created in the older V2.7 version. It is only applicable for V3.* library. Returns true if backward files are to be created, false otherwise.


getFileBackwardEnvVar

public static int getFileBackwardEnvVar()
                                 throws CDFException
Gets the indication of the CDF_FILEBACKWARD environment variable.

Returns:
1 if the environment variable is set to true, 0 if not set or set to anything else.
Throws:
CDFException - if there was a problem

getChecksumEnvVar

public static long getChecksumEnvVar()
                              throws CDFException
Gets the indication of the CDF_CHECKSUM environment variable.

Returns:
1 if the environment variable is set to MD5, 0 if not set or set to anything else.
Throws:
CDFException - if there was a problem

getStatus

public long getStatus()
Gets the status of the most recent CDF JNI/library function call. This value can be examined and appropriate action can be taken.

The following example sends a signal to the JNI code to write a single data to the current CDF. JNI in turn performs the requested operation. It then checks to see whether the requested operation was successfully performed or not.

     variable.putSingleData(recNum, dimIndicies, data);
     long status = cdf.getStatus();
     if (status != CDF_OK) {
         String statusText = CDF.getStatusText(status);
         System.out.println ("status = "+statusText);
     }
 

Returns:
the status of the most recent CDF JNI/library function call

getStatusText

public static java.lang.String getStatusText(long statusCode)
Gets the status text of the most recent CDF JNI/library function call.

The following example shows how to obtain the text representation of the status code returned from the getStatus method:

     long status = cdf.getStatus();
     if (status != CDF_OK) {
         String statusText = CDF.getStatusText(status);
         System.out.println ("status = "+statusText);
     }
 

Parameters:
statusCode - status code to be translated

Returns:
she string representation of the passed status code

setInfoWarningOff

public void setInfoWarningOff()
Sets the informational (status code > 0) or warning messages (status code between -1 and -2000) coming from the CDF JNI/library function off. This is the default when a file is opened or created.


setInfoWarningOn

public void setInfoWarningOn()
Sets the informational (status code > 0) or warning messages (status code between -1 and -2000) coming from the CDF JNI/library function on.


toString

public java.lang.String toString()
Gets the name of this CDF.

Overrides:
toString in class java.lang.Object
Returns:
the name of this CDF

finalize

public void finalize()
              throws java.lang.Throwable
Do the necessary cleanup when garbage collector reaps it.

Overrides:
finalize in class java.lang.Object
Throws:
java.lang.Throwable - if there was a problem doing cleanup

getDelegate

public CDFDelegate getDelegate()
This is a placeholder for future expansions/extensions.

Returns:
CDFDelegate object

setDelegate

public void setDelegate(CDFDelegate delegate)
This is a placeholder for future expansions/extensions.


getAttributeID

public long getAttributeID(java.lang.String attrName)
Gets the id of the given attribute.

Parameters:
attrName - the name of the attribute to check

Returns:
the id of the named attribute if it exists, -1 otherwise

getAttribute

public Attribute getAttribute(long attrNum)
                       throws CDFException
Gets the attribute for the given attribute number.

Note: The attrNum may not necessarily correspond to the attribute number stored in the CDF file.

Parameters:
attrNum - the attribute number to get
Returns:
the Attribute object that corresponds to the requested attribute number

Throws:
CDFException - if the supplied attribute number does not exist

getAttribute

public Attribute getAttribute(java.lang.String attrName)
                       throws CDFException
Gets the attribute for the given attribute name.

The following example retrieves the attribute named "ValidMin":

     Attribute validMin = cdf.getAttribute("ValidMin");
 

Parameters:
attrName - the name of the attribute to get

Returns:
the Attribute object that corresponds to the requested attribute name
Throws:
CDFException - if the supplied attribute name does not exist

getAttributes

public java.util.Vector getAttributes()
Gets all the global and variable attributes defined for this CDF. The following example retrieves all the global and variable attributes:
     Vector attr = cdf.getAttributes();
 

Returns:
a vector that contains the global and variable attributes defined in this CDF

getGlobalAttributes

public java.util.Vector getGlobalAttributes()
Gets the global attributes defined for this CDF.

Returns:
A vector that contains the global attributes defined in this CDF

getVariableAttributes

public java.util.Vector getVariableAttributes()
Gets the variable attributes defined for this CDF.

Returns:
A vector that contains the variable attributes defined in this CDF

getOrphanAttributes

public java.util.Vector getOrphanAttributes()
Gets the variable attributes defined for this CDF that are not associated with any variables.

Returns:
A vector that contains the empty variable attributes defined in this CDF.

getVariableID

public long getVariableID(java.lang.String varName)
Gets the ID of the given variable.

Parameters:
varName - the name of the variable to check

Returns:
-1 if the variable does not exist. The variable id if the variable does exist.

getVariable

public Variable getVariable(long varNum)
                     throws CDFException
Gets the variable object for the given variable number.

Parameters:
varNum - variable number from which the variable is retrieved

Returns:
the variable object that corresponds to the variable id

Throws:
CDFException - if the supplied variable number does not exist

getVariable

public Variable getVariable(java.lang.String varName)
                     throws CDFException
Gets the variable object for the given variable name.

The following example retrieves a variable called "Longitude":

     Variable longitude = cdf.getVariable("Longitude");
 

Parameters:
varName - the variable name to get

Returns:
the variable object that corresponds to the variable name

Throws:
CDFException - if the supplied variable name does not exist

getVariables

public java.util.Vector getVariables()
Gets the z variables defined for this CDF.

Note: Since all CDFs opened or created with the CDFJava APIs are placed into zMODE 2, there are no rVarialbles. All variables are treated as zVariables.

Returns:
a Vector containing all the z variables defined in this CDF

getNumVars

public long getNumVars()
Gets the number of Z variables defined for this CDF.

Note: Since all CDFs opened or create with the CDFJava APIs are placed into zMODE 2, there are no rVarialbles. All variables are treated as zVariables.


getRecord

public java.util.Vector getRecord(long recNum,
                                  java.lang.String[] strVars)
                           throws CDFException
Retrieves a logical record that consists of single variable record(s) from an arbitrary number of CDF variables. This is a convenient method for reading one or more variables' data in a single call, instead of reading individual variable's data one at a time.

Parameters:
recNum - the record number to retrieve data from

strVars - the variable (array of variable names) to retrieve data from

Returns:
the requested record in a Java vector that contains the variables' data.
The first object in the vector corresponds to the first variable's record, the second object in the vector corresponds to the second variable's record, and so on.

Throws:
CDFException - if there was a problem getting a record

Note: A virtual variable record is returned if the given record does not exist. Any error during data retrieval will cause the process to stop (an exception thrown) and thus nothing (a null object) will be returned.


getRecord

public java.util.Vector getRecord(long recNum,
                                  java.lang.String[] strVars,
                                  long[] status)
                           throws CDFException
Retrieves a logical record that consists of single variable record(s) from an arbitrary number of CDF variables. This is a convenient method for reading one or more variables' data in a single call, instead of reading individual variable's data one at a time.

Parameters:
recNum - the record number to retrieve data from

strVars - the variable (array of variable names) to retrieve data from

status - the individual status (array of statuses) for reading each variable record

Returns:
the requested record in a Java vector that contains the variables' data.
The first object in the vector corresponds to the first variable's record, the second object in the vector corresponds to the second variable's record, and so on.

Throws:
CDFException - if there was a problem getting a record

Note: A virtual variable record is returned if the given record does not exist. Any error during data retrieval will cause the process to stop (an exception thrown) and thus nothing (a null object) will be returned.

The following example reads the 2nd record from Longitude and Temperature and prints their contents.

       String[] strVars = {"Longitude", "Temperature"};
       Vector record;
       long[] status = new long[2];
       record = cdf.getRecord(1L, strVars, status);

       // Check the contents of the 'status' array - optional

       // var: Longitude - data type: CDF_UINT2, dimensionality: 1:[3] 
       System.out.print ("    2nd record of Longitude -- ");
       for (int i=0; i < 3; i++)
            System.out.print (((int[])record.elementAt(0))[i]+" ");
       System.out.println ("");

       // var: Temperature -- data type: CDF_REAL4, dimensionality: 1:[3] 
       System.out.print ("    2nd record of Temperature -- ");
       for (int i=0; i < 3; i++)
            System.out.print (((float[])record.elementAt(1))[i]+" ");
       System.out.println ("");
 

getRecord

public java.util.Vector getRecord(long recNum,
                                  long[] varIDs)
                           throws CDFException
Retrieves a logical record that consists of single variable record(s) from an arbitrary number of CDF variables. This is a convenient method for reading one or more variables' data in a single call, instead of reading individual variable's data one at a time.

Parameters:
recNum - the record number to retrieve data from

varIDs - the variable IDs (array of variable IDs) to retrieve data from

Returns:
the requested record in a Java vector that contains the variables' data.
The first object in the vector corresponds to the first variable's record, the second object in the vector corresponds to the second variable's record, and so on.

Throws:
CDFException - if there was a problem getting a record

Note: A virtual variable record is returned if the given record does not exist. Any error during data retrieval will cause the process to stop (an exception thrown) and thus nothing (a null object) will be returned.


getRecord

public java.util.Vector getRecord(long recNum,
                                  long[] varIDs,
                                  long[] status)
                           throws CDFException
Retrieves a logical record that consists of single variable record(s) from an arbitrary number of CDF variables. This is a convenient method for reading one or more variables' data in a single call, instead of reading individual variable's data one at a time.

Parameters:
recNum - the record number to retrieve data from

varIDs - the variable IDs (array of variable IDs) to retrieve data from

status - the individual status (array of statuses) for reading each variable record

Returns:
the requested record in a Java vector that contains the variables' data.
The first object in the vector corresponds to the first variable's record, the second object in the vector corresponds to the second variable's record, and so on.

Throws:
CDFException - if there was a problem getting a record

Note: A virtual variable record is returned if the given record does not exist. Any error during data retrieval will cause the process to stop (an exception thrown) and thus nothing (a null object) will be returned.

The following example reads the 2nd record from Longitude (varIds[0]) and Temperature (varIDs[1]) and prints their contents.

       long[] varIDs = {2, 10};    // Obtained from Variable.getID()
       Vector record;
       long[] status = new long[2];
       record = cdf.getRecord(1L, varIDs, status);

       // Check the contents of the 'status' array - optional

       // var: Longitude - data type: CDF_UINT2, dimensionality: 1:[3]
       System.out.print ("    2nd record of Longitude -- ");
       for (int i=0; i < 3; i++)
            System.out.print (((int[])record.elementAt(0))[i]+" ");
       System.out.println ("");

       // var: Temperature - data type: CDF_REAL4, dimensionality: 1:[3]
       System.out.print ("    2nd record of Temperature -- ");
       for (int i=0; i < 3; i++)
            System.out.print (((float[])record.elementAt(1))[i]+" ");
       System.out.println ("");
 

putRecord

public void putRecord(long recNum,
                      java.lang.String[] strVars,
                      java.util.Vector myData)
               throws CDFException
Writes a logical record that consists of single variable record(s) from an arbitrary number of CDF variables. This is a convenient method for writing one or more variables' data in a single call, instead of writing individual variable's data one at a time.

Parameters:
recNum - the record number to write data to

strVars - the variable (array of variable names) to write data to

myData - a Java vector that contains the variables' data.
The first object in the vector corresponds to the first variable's record, the second object in the vector corresponds to the second variable's record, and so on.

Throws:
CDFException - if there was a problem writing the record for any of the variables

Note: Any error during the data writing will cause the process to stop (an exception thrown) and thus the operation will not be completed. Nothing will be done if the element counts of parameters don't match.


putRecord

public void putRecord(long recNum,
                      java.lang.String[] strVars,
                      java.util.Vector myData,
                      long[] status)
               throws CDFException
Writes a logical record that consists of single variable record(s) from an arbitrary number of CDF variables. This is a convenient method for writing one or more variables' data in a single call, instead of writing individual variable's data one at a time.

Parameters:
recNum - the record number to write data to

strVars - the variable (array of variable names) to write data to

myData - a Java vector that contains the variables' data.
The first object in the vector corresponds to the first variable's record, the second object in the vector corresponds to the second variable's record, and so on.

status - the individual status (array of statuses) for writing each variable record

Throws:
CDFException - if there was a problem writing the record for any of the variables

Note: Any error during the data writing will cause the process to stop (an exception thrown) and thus the operation will not be completed. Nothing will be done if the element counts of parameters don't match.

The following example writes the contents of a record (which consists of two CDF variables - Longitude and Temperature) to record number 2.

    String[] strVars = {"Longitude",     // variable names in CDF
                        "Temperature"};

   // Longitude -- data type: CDF_UINT2 dimensionality: 1:[3] 
   int[] longitude_data = {333, 444, 555};

   // Temperature -- data type: CDF_FLOAT dimensionality: 0:[] 
   Float temperature_data = new Float((float)999.99);

   Vector record = new Vector();
   record.add(longitude_data);
   record.add(temperature_data);

   cdf.putRecord(1L, strVars, record);  // Write a record to record #2
 

putRecord

public void putRecord(long recNum,
                      long[] varIDs,
                      java.util.Vector myData)
               throws CDFException
Writes a logical record that consists of single variable record(s) from an arbitrary number of CDF variables. This is a convenient method for writing one or more variables' data in a single call, instead of writing individual variable's data one at a time.

Parameters:
recNum - the record number to write data to

varIDs - the variable IDs (array of variable IDs) to write data to

myData - a Java vector that contains the variables' data.
The first object in the vector corresponds to the first variable's record, the second object in the vector corresponds to the second variable's record, and so on.

Throws:
CDFException - if there was a problem writing the record for any of the variables

Note: Any error during the data writing will cause the process to stop (an exception thrown) and thus the operation will not be completed. Nothing will be done if the element counts of parameters don't match.


putRecord

public void putRecord(long recNum,
                      long[] varIDs,
                      java.util.Vector myData,
                      long[] status)
               throws CDFException
Writes a logical record that consists of single variable record(s) from an arbitrary number of CDF variables. This is a convenient method for writing one or more variables' data in a single call, instead of writing individual variable's data one at a time.

Parameters:
recNum - the record number to write data to

varIDs - the variable IDs (array of variable IDs) to write data to

myData - a Java vector that contains the variables' data.
The first object in the vector corresponds to the first variable's record, the second object in the vector corresponds to the second variable's record, and so on.

status - the individual status (array of statuses) for writing each variable record

Throws:
CDFException - if there was a problem writing the record for any of the variables

Note: Any error during the data writing will cause the process to stop (an exception thrown) and thus the operation will not be completed. Nothing will be done if the element counts of parameters don't match.

The following example writes the contents of a record (which consists of two CDF variables - Longitude and Temperature) by using variable IDs (instead of variable names) to record number 2.

   long[] varIDs = {3, 9};   // Can be obtained from variable.getID()

   // Longitude -- data type: CDF_UINT2 dimensionality: 1:[3]
   int[] longitude_data = {333, 444, 555};

   // Temperature -- data type: CDF_FLOAT dimensionality: 0:[]
   Float temperature_data = new Float((float)999.99);

   Vector record = new Vector();
   record.add(longitude_data);
   record.add(temperature_data);

   cdf.putRecord(1L, varIDs, record);  // Write a record to record #2
 

setChecksum

public void setChecksum(long checksum)
                 throws CDFException
Specifies the checksum option applied to the CDF.

Parameters:
checksum - the checksum option to be used for this CDF. Currently, other than NO_CHECKSUM option, only MD5_CHECKSUM (using MD5 checksum algorithm) is supported.
Throws:
CDFException - if there was a problem with the passed option, setting the checksum or other vital infomation from this CDF file.

getChecksum

public long getChecksum()
Gets the checksum method, if any, applied to the CDF.

Returns:
the checksum method used for this CDF. Currently, it returns NONE_CHECKSUM (0) if no checksum is used; MD5_CHECKSUM (1) if MD5 method is used;
Throws:
CDFException - if there was a problem getting the checksum or other vital infomation from this CDF file

verifyChecksum

public long verifyChecksum()
                    throws CDFException
Verifies the data integrity of the CDF file from its checksum.

Returns:
The status of data integrity check through its checksum. it should return CDF_OK if the integrity check is fine. Or, it may return a value of CHECKSUM_ERROR indicating the data integrity was compromised. Or, it may return other CDF error if it has problem reading the CDF data filed(s). No need to use this method as when the file is open, its data integrity is automatically checked with the used checksum method.
Throws:
CDFException - if there was a problem getting the checksum or other vital infomation from this CDF file