gsfc.nssdc.cdf

Class CDF

java.lang.Object

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:

• All files are placed in zMODE 2 upon opening or creation
• Variable attributes are handled slightly differently from C.
  • Each variable has a java.util.Vector of attributes.
  • This vector contains only those vAttributes that have a z entry for this variable.
  • Therefore, the index for a given variable Attribute may not be the same for another variable.

Supported dataTypes and their mappings

CDF dataType	Java dataType	Read/Write
CDF_BYTE	java.lang.Byte	Y/Y
CDF_INT1	java.lang.Byte	Y/Y
CDF_UINT1	java.lang.Short	Y/Y
CDF_INT2	java.lang.Short	Y/Y
CDF_UINT2	java.lang.Integer	Y/Y
CDF_INT4	java.lang.Integer	Y/Y
CDF_UINT4	java.lang.Long	Y/Y
CDF_INT8	java.lang.Long	Y/Y
CDF_FLOAT	java.lang.Float	Y/Y
CDF_REAL4	java.lang.Float	Y/Y
CDF_DOUBLE	java.lang.Double	Y/Y
CDF_REAL8	java.lang.Double	Y/Y
CDF_EPOCH	java.lang.Double	Y/Y
CDF_EPOCH16	java.lang.Double[	Y/Y
CDF_TIME_TT2000	java.lang.Long	Y/Y
CDF_CHAR	java.lang.String	Y/Y
CDF_UCHAR	java.lang.String	Y/Y

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, ARM_BIG_DECODING, ARM_BIG_ENCODING, ARM_LITTLE_DECODING, ARM_LITTLE_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_STRINGS, 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, BADDATE_LEAPSECOND_UPDATED, BeginUnixTimeEPOCH, BeginUnixTimeEPOCH16, BLOCKINGFACTOR_TOO_SMALL, BLOCKINGFACTOR_TOO_SMALL2, CANNOT_ALLOCATE_RECORDS, CANNOT_CHANGE, CANNOT_COMPRESS, CANNOT_COPY, CANNOT_INSERT_RECORDS, CANNOT_SPARSEARRAYS, CANNOT_SPARSERECORDS, CDF_, CDF_ACCESS_, CDF_ATTR_NAME_LEN, CDF_ATTR_NAME_LEN256, 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_INT8, CDF_INTERNAL_ERROR, CDF_LEAPSECONDLASTUPDATED_, 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_TIME_TT2000, CDF_UCHAR, CDF_UINT1, CDF_UINT2, CDF_UINT4, CDF_VAR_NAME_LEN, CDF_VAR_NAME_LEN256, 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_EPOCH16_PADVALUE, DEFAULT_FLOAT_PADVALUE, DEFAULT_INT1_PADVALUE, DEFAULT_INT2_PADVALUE, DEFAULT_INT4_PADVALUE, DEFAULT_INT8_PADVALUE, DEFAULT_REAL4_PADVALUE, DEFAULT_REAL8_PADVALUE, DEFAULT_TT2000_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, EPOCH4_STRING_LEN, EPOCH4_STRING_LEN_EXTEND, EPOCHx_FORMAT_MAX, EPOCHx_STRING_MAX, FILLED_TT2000_VALUE, FORCED_PARAMETER, FUNCTION_NOT_SUPPORTED, gENTRY_, gENTRY_DATA_, gENTRY_DATASPEC_, gENTRY_DATATYPE_, gENTRY_EXISTENCE_, gENTRY_NUMELEMS_, GET_, GETCDFCHECKSUM_, GETCDFFILEBACKWARD_, GETCDFVALIDATE_, GETLEAPSECONDSENVVAR_, GLOBAL_SCOPE, GZIP_COMPRESSION, HOST_DECODING, HOST_ENCODING, HP_DECODING, HP_ENCODING, HUFF_COMPRESSION, IA64VMSd_DECODING, IA64VMSd_ENCODING, IA64VMSg_DECODING, IA64VMSg_ENCODING, IA64VMSi_DECODING, IA64VMSi_ENCODING, 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, ILLEGAL_TT2000_VALUE, IS_A_NETCDF, 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, PPC_DECODING, PPC_ENCODING, 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_, rENTRY_NUMSTRINGS_, rENTRY_STRINGSDATA_, 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_RECORDS_RENUMBER_, 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_, STRINGDELIMITER, SUN_DECODING, SUN_ENCODING, TOO_MANY_PARMS, TOO_MANY_VARS, TRY_TO_READ_NONSTRING_DATA, TT2000_0_STRING_LEN, TT2000_1_STRING_LEN, TT2000_2_STRING_LEN, TT2000_3_STRING_LEN, TT2000_4_STRING_LEN, TT2000_CDF_MAYNEEDUPDATE, TT2000_TIME_ERROR, TT2000_USED_OUTDATED_TABLE, UNABLE_TO_PROCESS_CDF, UNKNOWN_COMPRESSION, UNKNOWN_SPARSENESS, UNSUPPORTED_OPERATION, VALIDATE_, VALIDATEFILEoff, VALIDATEFILEon, 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_, zENTRY_NUMSTRINGS_, zENTRY_STRINGSDATA_, ZLIB_COMPRESS_ERROR, ZLIB_UNCOMPRESS_ERROR, 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_RECORDS_RENUMBER_, zVAR_RECVARY_, zVAR_RESERVEPERCENT_, zVAR_SEQDATA_, zVAR_SEQPOS_, zVAR_SPARSEARRAYS_, zVAR_SPARSERECORDS_, zVARs_CACHESIZE_, zVARs_MAXREC_, zVARs_RECDATA_, zVARs_RECNUMBER_

Method Summary

Modifier and Type	Method and Description
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 value 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 value 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.
long	getLeapSecondLastUpdated() Gets the date that the CDF has the last leap second updated.
static java.lang.String	getLeapSecondsTableEnvVar() Gets the the CDF_LEAPSECONDSTABLE (or CDF$LEAPSECONDSTABLE on VMS) environment variable.
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.
static boolean	getValidate() Gets the file validation mode.
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	setLeapSecondLastUpdated(long lastUpdated) Set the leap second last updated for this CDF.
void	setMajority(long majority) Sets the variable majority for this CDF.
static void	setValidate(long mode) Sets the file validation mode so that when a CDF file is open, it will be validated accordingly.
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. (NEW) Each open CDF file is subjected to a default data validating process (some overheads) that will perform sanity checks. To overwrite it, you can use one of two ways: 1) Use the CDF static method setValidate before calling the open method: CDF.setValidate (VALIDATEFILEoff); 2) Set the environment variable CDF_VALIDATE (CDF$VALIDATE on VMS) to no

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.

Returns:

The library version in string

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.

Returns:

the string for CDF copy right note

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
• PPC_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
• PPC_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

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 value 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

getLeapSecondsTableEnvVar

public static java.lang.String getLeapSecondsTableEnvVar()
                                                  throws CDFException

Gets the the CDF_LEAPSECONDSTABLE (or CDF$LEAPSECONDSTABLE on VMS) environment variable.

Returns:

the string the environment variable is set to, null if not set

Throws:

CDFException - if there was a problem

getChecksumEnvVar

public static long getChecksumEnvVar()
                              throws CDFException

Gets the value 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

setValidate

public static void setValidate(long mode)
                        throws CDFException

Sets the file validation mode so that when a CDF file is open, it will be validated accordingly. Setting this flag will overwrite environment varibale CDF_VALIDATE (or CDF$VALIDATE on OpenVMS) if it is set. All CDF files open after this static method call will be applied.

Parameters:

mode - The mode indicates whether to validate CDF(s) while open. VALIDATEFILEon means all files are subjected to ve validated. VALIDATEFILEoff means no data validation will be performed.

Throws:

CDFException - if there was a problem

getValidate

public static boolean getValidate()

Gets the file validation mode.

Returns:

The mode indicating whether the CDF file is to be validated when it is open. Returns true if it will be validated, false otherwise.

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.

Parameters:

delegate - The CDFDelegate executing the command

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.

Returns:

the numer of variables 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;

setLeapSecondLastUpdated

public void setLeapSecondLastUpdated(long lastUpdated)
                              throws CDFException

Set the leap second last updated for this CDF. Normally, a new CDF is created, this field is set automatically. Only to call this method if the CDF is based on an existing one.

Parameters:

lastUpdated - The last date that the leap second was updated. It is in YYYYMMDD form.

Throws:

CDFException - If a problem occurred in setting the desired field.

getLeapSecondLastUpdated

public long getLeapSecondLastUpdated()

Gets the date that the CDF has the last leap second updated.

Returns:

the date in YYYYMMDD that the last leap second was updated when the CDF is based (relavant to TT2000 variables).

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