gsfc.nssdc.cdf
Class Variable

java.lang.Object
  extended bygsfc.nssdc.cdf.Variable
All Implemented Interfaces:
CDFConstants, CDFObject

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

The Variable class defines a CDF variable.

Notes: Since the CDF JavaAPI always uses zMODE = 2, all variables are by default, zVariables.

Version:
1.0, 2.0 03/18/05 Selection of current CDF and variable are 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.
See Also:
Attribute, Entry

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_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_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_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_, 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_, 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, 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_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, NOT_A_CDF, NOT_A_CDF_OR_NOT_SUPPORTED, NOVARY, NULL_, OPEN_, OPTIMAL_ENCODING_TREES, 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_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 allocateBlock(long firstRec, long lastRec)
          Allocates a range of records for this variable.
 void allocateRecords(long num0toRecords)
          Allocates a number of records, starting from record number 0.
 boolean checkPadValueExistence()
          Checks if the pad value has been defined for this variable.
 void concatenateDataRecords(Variable destVar)
          Concatenates this variable's data records to the destination variable.
 long confirmCacheSize()
          Gets the number of 512-byte cache buffers defined for this variable.
 long confirmPadValue()
          Checks the existence of an explicitly specified pad value for the current z variable.
 long confirmReservePercent()
          Gets the reserve percentage set for this variable.
 Variable copy(CDF destCDF, java.lang.String varName)
          Copies this variable into a new variable and puts it into the designated CDF file.
 Variable copy(java.lang.String varName)
          Copies this variable to a new variable.
 void copyDataRecords(Variable destVar)
          Copies this variable's data to the destination variable.
static Variable create(CDF myCDF, java.lang.String varName, long dataType, long numElements, long numDims, long[] dimSizes, long recVary, long[] dimVarys)
          Creates a variable.
 void delete()
          Deletes this variable.
 void deleteRecords(long firstRec, long lastRec)
          Deletes a range of records from this variable.
 Variable duplicate(CDF destCDF, java.lang.String varName)
          Duplicates this variable and put it into the designated CDF file.
 Variable duplicate(java.lang.String varName)
          Duplicates this variable to a new variable.
 long getAllocatedFrom(long recNum)
          Inquires the next allocated record at or after a given record for this variable.
 long getAllocatedTo(long firstRec)
          Inquires the last allocated record (before the next unallocated record) at or after a given record for this variable.
 java.util.Vector getAttributes()
          Returns the variable attributes that are associated with this variable.
 long getBlockingFactor()
          Gets the blocking factor for this variable.
 java.lang.String getCompression()
          Gets the string representation of the compression type and parameters set for this variable.
 long[] getCompressionParms()
          Sets the compression parameters of this variable.
 long getCompressionPct()
          Gets the compression percentage rate of this variable.
 long getCompressionType()
          Gets the compression type of this variable.
 long getDataType()
          Gets the CDF data type of this variable.
 long[] getDimSizes()
          Gets the dimensions size of this variable.
 long[] getDimVariances()
          Gets the dimension variances for this variable.
 java.lang.Object getEntryData(java.lang.String attrName)
          Gets the attribute entry data for this variable.
 java.lang.Object getHyperData(long recNum, long recCount, long recInterval, long[] dimIndices, long[] dimCounts, long[] dimIntervals)
          Reads one or more values from the current z variable.
 CDFData getHyperDataObject(long recNum, long recCount, long recInterval, long[] dimIndices, long[] dimCounts, long[] dimIntervals)
          Reads one or more values from the current z variable.
 long getID()
          Gets the ID of this variable.
 long getMaxAllocatedRecord()
          Gets the maximum allocated record number for this variable.
 long getMaxWrittenRecord()
          Gets the last written record number, beginning with 0.
 CDF getMyCDF()
          Gets the CDF object to which this variable belongs.
 java.lang.String getName()
          Gets the name of this variable.
 long getNumAllocatedRecords()
          Gets the number of records allocated for this variable.
 long getNumDims()
          Gets the number of dimensions for this variable.
 long getNumElements()
          Gets the number of elements for this variable.
 long getNumWrittenRecords()
          Gets the number of records physically written (not allocated) for this variable.
 java.lang.Object getPadValue()
          Gets the pad value set for this variable.
 java.lang.Object getRecord(long recNum)
          Gets a single record from this variable.
 CDFData getRecordObject(long recNum)
          Get a single record of data from this variable.
 CDFData getRecordsObject(long recNum, long numRecs)
          Get a number of records of data from this variable.
 boolean getRecVariance()
          Gets the value of record variance.
 java.lang.Object getScalarData()
          Gets the scalar data from a non-record varying 0-dimensional variable.
 java.lang.Object getScalarData(long recNum)
          Get the scalar data from a record varying 0-dimensional variable.
 CDFData getScalarDataObject()
          Get the scalar data from a non-record varying 0-dimensional variable.
 CDFData getScalarDataObject(long recNum)
          Get the scalar data from this record varying 0-dimensional variable.
 java.lang.Object getSingleData(long recNum, long[] indices)
          Gets a single data value.
 CDFData getSingleDataObject(long recNum, long[] indices)
          Gets a single data object from this variable.
 long getSparseRecords()
          Gets the sparse record type for this variable.
 void putEntry(Attribute attr, long dataType, java.lang.Object data)
          Creates an attribute entry for this variable.
 void putEntry(java.lang.String attrName, long dataType, java.lang.Object data)
          Creates an attribute entry for this variable.
 CDFData putHyperData(long recNum, long recCount, long recInterval, long[] dimIndices, long[] dimCounts, long[] dimIntervals, java.lang.Object data)
          Writes one or more values from the current z variable.
 CDFData putRecord(long recNum, java.lang.Object data)
          Adds a single record to a record-varying variable.
 CDFData putRecord(java.lang.Object data)
          Adds a single record to a non-record-varying variable.
 CDFData putScalarData(long recNum, java.lang.Object data)
          Adds a scalar data to this variable (of 0 dimensional).
 CDFData putScalarData(java.lang.Object data)
          Adds a scalar data to this variable (of 0 dimensional).
 CDFData putSingleData(long recNum, long[] indices, java.lang.Object data)
          Adds a single data value to this variable.
 void rename(java.lang.String newName)
          Renames the current variable.
 void selectCacheSize(long cacheSize)
          Sets the number of 512-byte cache buffers to be used.
 void selectReservePercent(long reservePercent)
          Sets the reserve percentage to be used for this variable.
 void setBlockingFactor(long blockingFactor)
          Sets the blocking factor for this variable.
 void setCompression(long cType, long[] cParms)
          Sets the compression type and parameters for this variable.
 void setDimVariances(long[] dimVariances)
          Sets the dimension variances for this variable.
 void setInitialRecords(long nRecords)
          Sets the number of records to be written initially for this variable.
 void setPadValue(java.lang.Object padValue)
          Sets the pad value for this variable.
 void setRecVariance(long recVariance)
          Sets the record variance for this variable.
 void setSparseRecords(long sparseRecords)
          Sets the sparse record type for this variable.
 java.lang.String toString()
          Gets the name of this variable.
 void updateDataSpec(long dataType, long numElements)
          Update the data specification (data type and number of elements) of the variable.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

create

public static Variable create(CDF myCDF,
                              java.lang.String varName,
                              long dataType,
                              long numElements,
                              long numDims,
                              long[] dimSizes,
                              long recVary,
                              long[] dimVarys)
                       throws CDFException
Creates a variable.

The following example creates a variable called "Longitude" that is scalar (non-array) and record-varying:

     longitude = Variable.create(cdf, "Longitude", CDF_INT2,
                                 1L, 0L, new long [] {1}, 
                                 VARY,
                                 new long [] {NOVARY});
 
The following example creates a variable called "TestData" whose data is 2-dimensional (3 x 2), record variance is TURE, and dimension variances are TRUE.
     data = Variable.create(cdf, "TestData", CDF_INT2,
                            1L, 2L, new long [] {3,2}, 
                            VARY,
                            new long [] {VARY, VARY});  
 

Parameters:
myCDF - the CDF to which this variable belongs

varName - the name of the variable to create

dataType - the CDF data type for this variable that should be one of the following:
  • CDF_BYTE - 1-byte, signed integer
  • CDF_CHAR - 1-byte, signed character
  • CDF_INT1 - 1-byte, signed integer
  • CDF_UCHAR - 1-byte, unsigned character
  • CDF_UINT1 - 1-byte, unsigned integer
  • CDF_INT2 - 2-byte, signed integer
  • CDF_UNIT2 - 2-byte, unsigned integer
  • CDF_INT4 - 4-byte, signed integer
  • CDF_UINT4 - 4-byte, unsigned integer
  • CDF_REAL4 - 4-byte, floating point
  • CDF_FLOAT - 4-byte, floating point
  • CDF_REAL8 - 8-byte, floating point
  • CDF_DOUBLE - 8-byte, floating point
  • CDF_EPOCH - 8-byte, floating point
  • CDF_EPOCH16 - 2*8-byte, floating point
numElements - for CDF_CHAR and CDF_UCHAR this is the string length, 1 otherwise

numDims - the dimensionality

dimSizes - The dimension sizes. An array of length numDims indicating the size of each dimension

recVary - the record variance that should be either VARY or NOVARY

dimVarys - The dimension variance(s). Each dimension variance should be either VARY or NOVARY.

Returns:
newly created Variable object

Throws:
CDFException - if there is a problem creating a variable

delete

public void delete()
            throws CDFException
Deletes this variable.

Specified by:
delete in interface CDFObject
Throws:
CDFException - if there was an error deleting this variable

rename

public void rename(java.lang.String newName)
            throws CDFException
Renames the current variable.

Specified by:
rename in interface CDFObject
Parameters:
newName - the new variable name

Throws:
CDFException - if there was a problem renaming this variable

copy

public Variable copy(java.lang.String varName)
              throws CDFException
Copies this variable to a new variable. This method only copies the metadata associated with this variable. The duplicate method in this class should be used if the user wants to copy a variable with data and metadata.

Parameters:
varName - the name of the variable to copy this variable into

Returns:
newly copied variable
Throws:
CDFException - if there was a problem copying a variable


copy

public Variable copy(CDF destCDF,
                     java.lang.String varName)
              throws CDFException
Copies this variable into a new variable and puts it into the designated CDF file. This method only copies the metadata associated with this variable. The duplicate method in this class should be used if the user wants to copy a variable with data and metadata.

Parameters:
destCDF - the destination CDF into which copy this variable
varName - the new variable name

Returns:
newly copied variable
Throws:
CDFException - if there was a problem copying a variable


duplicate

public Variable duplicate(java.lang.String varName)
                   throws CDFException
Duplicates this variable to a new variable.

Note: This copies everything from the existing variable to a new variable. It includes the metadata associated with this variable, all data records as well as other information such as blocking factor/compression/sparseness/pad value.

Parameters:
varName - the name of the variable to duplicate this variable into

Returns:
newly duplicated variable
Throws:
CDFException - if there was a problem duplicating a variable


duplicate

public Variable duplicate(CDF destCDF,
                          java.lang.String varName)
                   throws CDFException
Duplicates this variable and put it into the designated CDF file.

Note: This copies everything from the current variable to a new variable. It includes the metadata associated with this variable, all data records as well as other information such as blocking factor/compression/sparseness/pad value.

Parameters:
destCDF - the destination CDF to duplicate this variable into

varName - the name of the variable to duplicate this variable into

Returns:
newly duplicated variable
Throws:
CDFException - if there was a problem duplicating a variable


copyDataRecords

public void copyDataRecords(Variable destVar)
                     throws CDFException
Copies this variable's data to the destination variable.

Note: This copies data records from the current variable to the destination variable. The metadata associated with the destination variable will be not changed.

The current CDF file MUST be saved first (by calling the save() method) before 'copying/duplicating data records' operation is performed. Otherwise the program will either fail or produce undesired results.

Parameters:
destVar - the destination variable to copy data into

Throws:
CDFException - if there was a problem copying data records

concatenateDataRecords

public void concatenateDataRecords(Variable destVar)
                            throws CDFException
Concatenates this variable's data records to the destination variable.

Note: This copies only the data records from the current variable to the destination variable. The metadata associated with the destination variable will be not changed.

Parameters:
destVar - the destination variable to copy data records into

Throws:
CDFException - if there was a problem copying data records

getEntryData

public java.lang.Object getEntryData(java.lang.String attrName)
                              throws CDFException
Gets the attribute entry data for this variable.

The following examples retrieves the 'Longitude' variable entry for the attribute VALIDMIN:

     Variable var = cdf.getVariable("Longitude");  
     float longitude = (float) var.getEntryData("VALIDMIN");
 

Parameters:
attrName - the name of the attribute to get entry data from

Returns:
the attribute entry data for this variable

Throws:
CDFException - if there was a problem getting entry data

getSingleData

public java.lang.Object getSingleData(long recNum,
                                      long[] indices)
                               throws CDFException
Gets a single data value. This method is useful for extracting a specific item among many items.

Let's assume that variable TestData is defined to be 1-dimensional array that has 3 elements in it. The following example extracts the last element from the second record:

     Variable var = cdf.getVariable("TestData");
     int data = (int) var.getSingleData(1L, new long [] {2});
 
Let's assume that variable TestData is defined to be 2-dimensional (3x2 - 3 rows and 2 columns) array. The following example extracts the first element of the second row from the first record:
     Variable var = cdf.getVariable("TestData");
     int data = (int) var.getSingleData(0L, new long [] {1,0});
 

Parameters:
recNum - the record number to retrieve data from

indices - the index, within a record, to extract data from

Returns:
extracted single data value

Throws:
CDFException - if there was a problem extracting data

getSingleDataObject

public CDFData getSingleDataObject(long recNum,
                                   long[] indices)
                            throws CDFException
Gets a single data object from this variable. The value read is put into an CDFData object. This method is identical to the getSingleData method except that the extracted data is encapsulated inside the CDFData object along with other information such as record number, record count, record interval, dimension indices, dimension counts, and dimension intervals.

Parameters:
recNum - the record number to retrieve data from

indices - the index, within a record, to extract data from

Returns:
CDFData object containing the requested data

Throws:
CDFException - if there was a problem extracting data

getRecord

public java.lang.Object getRecord(long recNum)
                           throws CDFException
Gets a single record from this variable.

Let's assume that variable TestData is defined to be 2-dimensional (3x2 - 3 rows and 2 columns). The following example extracts the entire record (containing 6 elements) from the first record:

     Variable var = cdf.getVariable("TestData");
     int[][] data = (int [][]) var.getRecord(0L);
 

Parameters:
recNum - the record number to retrieve data from

Returns:
the requested data record
Throws:
CDFException - if there was a problem getting a record

getRecordObject

public CDFData getRecordObject(long recNum)
                        throws CDFException
Get a single record of data from this variable. The values read are put into an CDFData object. This method is identical to the getRecord method except that the extracted data is encapsulated inside the CDFData object along with other information such as record number, record count, record interval, dimension indices, dimension counts, and dimension intervals.

Parameters:
recNum - the record number to retrieve data from

Returns:
CDFObject containing the requested data record

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

getRecordsObject

public CDFData getRecordsObject(long recNum,
                                long numRecs)
                         throws CDFException
Get a number of records of data from this variable. The values read are put into an CDFData object.

Parameters:
recNum - the record number to start to retrieve data from

numRecs - the number of records to retrieve

Returns:
CDFObject containing the requested data record(s)

Throws:
CDFException - if there was a problem getting the record(s)

getScalarData

public java.lang.Object getScalarData()
                               throws CDFException
Gets the scalar data from a non-record varying 0-dimensional variable.

Returns:
the variable data from this variable

Throws:
CDFException - if there was a problem getting data

getScalarData

public java.lang.Object getScalarData(long recNum)
                               throws CDFException
Get the scalar data from a record varying 0-dimensional variable.

Parameters:
recNum - The record number to retrieve data from

Returns:
the variable data from this variable

Throws:
CDFException - if there was a problem getting data

getScalarDataObject

public CDFData getScalarDataObject()
                            throws CDFException
Get the scalar data from a non-record varying 0-dimensional variable. This method is identical to the getScalarData method except that the extracted data is encapsulated inside the CDFData object along with other information such as record number, record count, record interval, dimension indices, dimension counts, and dimension intervals.

Returns:
the variable data from this variable
Throws:
CDFException - if there was a problem getting data

getScalarDataObject

public CDFData getScalarDataObject(long recNum)
                            throws CDFException
Get the scalar data from this record varying 0-dimensional variable. This method is identical to the getScalarData method except that the extracted data is encapsulated inside the CDFData object along with other information such as record number, record count, record interval, dimension indices, dimension counts, and dimension intervals.

Parameters:
recNum - the record number to retrieve data from

Returns:
the variable data from this variable
Throws:
CDFException - if there was a problem getting data

getHyperData

public java.lang.Object getHyperData(long recNum,
                                     long recCount,
                                     long recInterval,
                                     long[] dimIndices,
                                     long[] dimCounts,
                                     long[] dimIntervals)
                              throws CDFException
Reads one or more values from the current z variable. The values are based on the current record number, current record count, current record interval, current dimension indices, current dimension counts, and current dimension intervals.

Let's assume that variable TestData is defined to be 2-dimensional (3x2 - 3 rows and 2 columns). The following example extracts the entire record (containing 6 elements) from the first, second, and third records:

     Variable var = cdf.getVariable("TestData");
     int[][][] data = (int [][][]) var.getHyperData (0L, 3L, 1L,
                                                     new long[] {0, 0},
                                                     new long[] {3, 2},
                                                     new long[] {1, 1});
 
The following example will extract the entire record from the first record:
     Variable var = cdf.getVariable("TestData");
     int[][] data = (int [][]) var.getHyperData (0L, 1L, 1L,
                                                 new long[] {0, 0},
                                                 new long[] {3, 2},
                                                 new long[] {1, 1});
 
Note: it returns a 2-dimensional object as only one record is involved. The following example will extract the second row from the first, and third records:
     Variable var = cdf.getVariable("TestData");
     int[][] data = (int [][]) var.getHyperData (0L, 3L, 2L,
                                                 new long[] {1, 0},
                                                 new long[] {1, 2},
                                                 new long[] {1, 1});
 
The following example will extract the first column from the first and second records:
     Variable var = cdf.getVariable("TestData");
     int[][] data = (int [][]) var.getHyperData (0L, 2L, 1L,
                                                 new long[] {0, 0},
                                                 new long[] {3, 1},
                                                 new long[] {1, 1});
 

Parameters:
recNum - the record number at which data search begins

recCount - the number of records to read

recInterval - the number of records to skip between reads

dimIndices - the dimension index within a record at which data search begins

dimCounts - the number of elements to read from dimIndices

dimIntervals - the number of elements to skip between reads

Returns:
the variable data specified by recNum, recCount, recInterval, dimIndices, dimCounts, and dimIntervals

Throws:
CDFException - if there was a problem getting data

getHyperDataObject

public CDFData getHyperDataObject(long recNum,
                                  long recCount,
                                  long recInterval,
                                  long[] dimIndices,
                                  long[] dimCounts,
                                  long[] dimIntervals)
                           throws CDFException
Reads one or more values from the current z variable. The values are read based on the current record number, current record count, current record interval, current dimension indices, current dimension counts, and current dimension intervals. The values read are put into an CDFData object.

Parameters:
recNum - the record number at which data search begins
recCount - the number of records to read
recInterval - the number of records to skip between reads
dimIndices - the dimension index within a record at which data search begins
dimCounts - the number of elements to read from dimIndices
dimIntervals - the number of elements to skip between reads

Returns:
CDFData object that contains the variable data specified by recNum, recCount, recInterval, dimIndices, dimCounts, and dimIntervals as well as the information passed to this method plus the number of dimensions and the number of elements for this variable.

Throws:
CDFException - if there was a problem getting data

putEntry

public void putEntry(java.lang.String attrName,
                     long dataType,
                     java.lang.Object data)
              throws CDFException
Creates an attribute entry for this variable.

The following example creates a variable entry for the variable "Longitude" associated with the attribute "VALIDMIN":

     Variable longitude = cdf.getVariable("Longitude");
     longitude.putEntry("VALIDMIN", CDF_INT2, new Short((short)180));
 

Parameters:
attrName - the attribute to which this attribute entry is attached
dataType - the CDF data type of the entry data - see the description of the create method in this class for a list of the CDF data types supported
data - the attribute entry data to be added
Throws:
CDFException - if a problem occurs putting an entry
See Also:
Attribute, Entry

putEntry

public void putEntry(Attribute attr,
                     long dataType,
                     java.lang.Object data)
              throws CDFException
Creates an attribute entry for this variable. The following example creates a variable entry for the variable "Longitude" associated with the attribute "VALIDMIN":
     Variable longitude = cdf.getVariable("Longitude");
     Attribute validMin = Attribute.create(cdf, "VALIDMIN",
                                           VARIABLE_SCOPE);
     Entry.create(validMin, longitude.getID(), CDF_INT2,
                  new Short((short)10)); 

OR

longitude.putEntry(validMin, CDF_INT2, new Short((short)180));

Parameters:
attr - the attribute to which this attribute entry is attached

dataType - the CDF data type of the entry data - see the description of the create method in this class for a list of the CDF data types supported
data - the attribute entry data to be added

Throws:
CDFException - if a problem occurs putting an entry
See Also:
Attribute, Entry

putSingleData

public CDFData putSingleData(long recNum,
                             long[] indices,
                             java.lang.Object data)
                      throws CDFException
Adds a single data value to this variable. This method is used to specify a particular element in a record (if a record is comprised of multiple elements). If a record contains 3 elements, the following example will write the second element to record number 0, leaving the first and third elements unwritten.
    longitude = cdf.getVariable("Longitude");
    longitude.putSingleData(0L, new long[] {1}, new Short((short)200));
           or
    longitude.putSingleData(0L, new long[] {1}, longitudeData[1]);
 

Parameters:
recNum - the record number to which this data belongs

indices - the index (location) in the specified record

data - the data to be added

Returns:
CDFData object containing the user specified data

Throws:
CDFException - if there was an error writing data

putScalarData

public CDFData putScalarData(long recNum,
                             java.lang.Object data)
                      throws CDFException
Adds a scalar data to this variable (of 0 dimensional). This method should be used if a variable is defined as record-varying and non-array. The following example will write data to record number 0.
    longitude = cdf.getVariable("Longitude");
    longitude.putScalarData(0L, new Short((short)200));
           or
    longitude.putScalarData(0L, longitudeData[0]);
 

Parameters:
recNum - the record number to which this data belongs

data - the data to be added

Returns:
CDFData object containing the user specified data

Throws:
CDFException - if there was an error writing data

putScalarData

public CDFData putScalarData(java.lang.Object data)
                      throws CDFException
Adds a scalar data to this variable (of 0 dimensional). This method should be used if a variable is defined as non-record-varying and non-array. Note that there'll be only one record exist if a variable is defined as non-record-varying. The following example will write data to record number 0.
    longitude = cdf.getVariable("Longitude");
    longitude.putScalarData(new Short((short)200));
           or
    longitude.putScalarData(longitudeData[0]);
 

Parameters:
data - the data to be added

Returns:
CDFData object containing the user specified data

Throws:
CDFException - if there was an error writing data

putRecord

public CDFData putRecord(long recNum,
                         java.lang.Object data)
                  throws CDFException
Adds a single record to a record-varying variable. This method should be used if a record contains one or more elements.
    The following example adds a scalar data to record number 0: 

longitude = cdf.getVariable("Longitude"); longitude.putRecord(0L, new Short((short)200));

The following example adds multiple elements (array) to record number 0:

short [] longitudeData = {10, 20, 30}; longitude = cdf.getVariable("Longitude"); longitude.putRecord(0L, longitudeData);

Parameters:
recNum - the record number to which this data belongs

data - the data to be added

Returns:
CDFData object containing the user specified data

Throws:
CDFException - if there was a problem writing data

putRecord

public CDFData putRecord(java.lang.Object data)
                  throws CDFException
Adds a single record to a non-record-varying variable. This method should be used if a record contains one element or multiple elements.
    The following example adds a scalar data to record number 0: 

longitude = cdf.getVariable("Longitude"); longitude.putRecord(new Short((short)200));

The following example adds multiple elements (array) to record number 0:

short [] longitudeData = {10, 20, 30}; longitude = cdf.getVariable("Longitude"); longitude.putRecord(longitudeData);

Parameters:
data - the data to be added

Returns:
CDFData object containing the user specified data

Throws:
CDFException - if there was a problem writing data

putHyperData

public CDFData putHyperData(long recNum,
                            long recCount,
                            long recInterval,
                            long[] dimIndices,
                            long[] dimCounts,
                            long[] dimIntervals,
                            java.lang.Object data)
                     throws CDFException
Writes one or more values from the current z variable. The values are written based on the current record number, current record count, current record interval, current dimension indices, current dimension counts, and current dimension intervals. The values read are put into an CDFData object. Although this method returns a CDFData object, it is not necessary to capture the return value to a CDFData variable.

Let's assume that variable TestData is defined to be 2-dimensional (3x2 - 3 rows and 2 columns). The following example writes the entire record (containing 6 elements) to the first, second, and third records:

     long [][][] testData = {{{10,20},{30,40},{50, 60}},
                             {{15,25},{45,55},{75, 85}}
                             {{90,95},{96,97},{2147483648L,4294967295L}}
                             };
     testData.putHyperData (0L, 3L, 1L,
                            new long[] {0, 0},
                            new long[] {3, 2},
                            new long[] {1, 1});
 
The following example will write the first two rows of testData to the first, third, and fifth records:
     testData.putHyperData (0L, 3L, 2L,
                            new long[] {0, 0},        
                            new long[] {2, 2},        
                            new long[] {1, 1});       
 

Parameters:
recNum - the record number at which data write begins

recCount - the number of records to write

recInterval - the number of records to skip between writes

dimIndices - the dimension index within a record at which data write begins

dimCounts - the number of elements to write from dimIndices

dimIntervals - the number of elements to skip between writes

data - the data to be written

Returns:
CDFData object that contains the variable data specified by recNum, recCount, recInterval, dimIndices, dimCounts, and dimIntervals as well as the information passed to this method plus the number of dimensions and the number of elements for this variable.

Throws:
CDFException - if there was a problem writing data

getMyCDF

public CDF getMyCDF()
Gets the CDF object to which this variable belongs.

Returns:
the CDF object to which this variable belongs

getCompressionType

public long getCompressionType()
Gets the compression type of this variable.

Returns:
the compression type of this variable

getCompressionPct

public long getCompressionPct()
Gets the compression percentage rate of this variable.

Returns:
the compression percentage rate of this variable

getCompressionParms

public long[] getCompressionParms()
Sets the compression parameters of this variable. This is only applicable for the GZIP compression method.

Returns:
the compression parameters of this variable

setCompression

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

Parameters:
cType - the compression type
cParms - the compression parameters that go with cType

Throws:
CDFException - if a problem occurs setting compression type and parameters

getCompression

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

Returns:
the string representation of the compression type and parameters for this variable

Throws:
CDFException - if a problem occurs getting the compression type and parameters

getNumDims

public long getNumDims()
Gets the number of dimensions for this variable.

Returns:
the number of dimensions for this variable

getDimSizes

public long[] getDimSizes()
Gets the dimensions size of this variable.

Returns:
the dimension size of this variable

getNumElements

public long getNumElements()
Gets the number of elements for this variable. For CDF_CHAR and CDF_UCHAR this is the number of characters in the string. For all other types this defaults to 1.

Returns:
the number of elements for this variable

getName

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

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

getID

public long getID()
Gets the ID of this variable.

Returns:
the ID of this variable

toString

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

Returns:
the name of this variable

setRecVariance

public void setRecVariance(long recVariance)
                    throws CDFException
Sets the record variance for this variable.

Parameters:
recVariance - the record variance that should be either VARY or NOVARY.

Throws:
CDFException - if a problem occurs setting the record variance

getRecVariance

public boolean getRecVariance()
Gets the value of record variance.

Returns:
True if this variable is record varying, False otherwise

setDimVariances

public void setDimVariances(long[] dimVariances)
                     throws CDFException
Sets the dimension variances for this variable.

Parameters:
dimVariances - the dimension variances for this variable

Throws:
CDFException - if a problem occurs setting the dimension variances

getDimVariances

public long[] getDimVariances()
Gets the dimension variances for this variable.

Returns:
the dimension variances for this variable

getDataType

public long getDataType()
Gets the CDF data type of this variable.

Returns:
the CDF data type of this variable

deleteRecords

public void deleteRecords(long firstRec,
                          long lastRec)
                   throws CDFException
Deletes a range of records from this variable.

Parameters:
firstRec - the first record to be deleted
lastRec - the last record to be deleted

Throws:
CDFException - if a problem occurs deleting records

allocateBlock

public void allocateBlock(long firstRec,
                          long lastRec)
                   throws CDFException
Allocates a range of records for this variable.

Parameters:
firstRec - the first record to be allocated
lastRec - the last record to be allocated

Throws:
CDFException - if a problem occurs allocating records

allocateRecords

public void allocateRecords(long num0toRecords)
                     throws CDFException
Allocates a number of records, starting from record number 0.

Parameters:
num0toRecords - the number of records to be allocated

Throws:
CDFException - if a problem occurs allocating records

getNumWrittenRecords

public long getNumWrittenRecords()
                          throws CDFException
Gets the number of records physically written (not allocated) for this variable.

Returns:
the number of records written physically

Throws:
CDFException - if a problem occurs getting the number of records written physically

getMaxWrittenRecord

public long getMaxWrittenRecord()
                         throws CDFException
Gets the last written record number, beginning with 0.

Returns:
the last written record number

Throws:
CDFException - if a problem occurs getting the last written record number

getNumAllocatedRecords

public long getNumAllocatedRecords()
                            throws CDFException
Gets the number of records allocated for this variable.

Returns:
the number of records allocated

Throws:
CDFException - if a problem occurs getting the number of records allocated

getMaxAllocatedRecord

public long getMaxAllocatedRecord()
                           throws CDFException
Gets the maximum allocated record number for this variable.

Returns:
the maximum allocated record number

Throws:
CDFException - if a problem occurs getting the maximum allocated record number

setPadValue

public void setPadValue(java.lang.Object padValue)
                 throws CDFException
Sets the pad value for this variable. This pad value is used, when storing data, for undefined values.

Parameters:
padValue - the pad value to be used for undefined values

Throws:
CDFException - if a problem occurs setting the pad value

checkPadValueExistence

public boolean checkPadValueExistence()
                               throws CDFException
Checks if the pad value has been defined for this variable. While the getPadValue() method always returns a pad value, it may simply be the default pad value (albeit the pad value was never defined by the user).

Returns:
Whether the user-defined pad value exists. It is either true or false.
  • true - pad value has been specified.
  • false - pad value is not specified.

    Note: The system default pad value is returned if getPadValue() is called.

Throws:
CDFException - if a problem occurs checking the existence of the pad value

getPadValue

public java.lang.Object getPadValue()
Gets the pad value set for this variable.

Returns:
the pad value set for this variable


setSparseRecords

public void setSparseRecords(long sparseRecords)
                      throws CDFException
Sets the sparse record type for this variable.

Parameters:
sparseRecords - sparse record type that should be one of the following types:
  • NO_SPARSERECORDS - The variable doesn't have sparse records.
  • PAD_SPARSERECORDS - The variable has pad-missing records.
  • PREV_SPARSERECORDS - The variable has previous-missing records.
Throws:
CDFException - if a problem occurs setting the sparse record type

getSparseRecords

public long getSparseRecords()
Gets the sparse record type for this variable.

Returns:
one of the following sparse record type is returned:
  • NO_SPARSERECORDS - means that no sparse records are defined
  • PAD_SPARSERECORDS - means that the variable's pad value is used when reading values from a missing record
  • PREV_SPARSERECORDS - means that values from the previous existing records are used when reading values from a missing record

setBlockingFactor

public void setBlockingFactor(long blockingFactor)
                       throws CDFException
Sets the blocking factor for this variable. The blocking factor has no effect for Non-Record varying (NRV) variables or muti-file CDFs.

Parameters:
blockingFactor - the blocking factor - a value of zero (0) indicates that the default blocking factor should be used

Throws:
CDFException - if a problem occurs setting the blocking factor

getBlockingFactor

public long getBlockingFactor()
                       throws CDFException
Gets the blocking factor for this variable.

Returns:
the blocking factor set this variable

Throws:
CDFException - if a problem occurs getting the blocking factor set for this variable

setInitialRecords

public void setInitialRecords(long nRecords)
                       throws CDFException
Sets the number of records to be written initially for this variable.

Parameters:
nRecords - the number of records to be written initially

Throws:
CDFException - if a problem occurs writing initial records

selectCacheSize

public void selectCacheSize(long cacheSize)
                     throws CDFException
Sets the number of 512-byte cache buffers to be used. This operation is not applicable for a single-file CDF.

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

Throws:
CDFException - if a problem occurs allocating cache buffers

confirmCacheSize

public long confirmCacheSize()
                      throws CDFException
Gets the number of 512-byte cache buffers defined for this variable.

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

Throws:
CDFException - if a problem occurs getting the number of cache buffers set for this variable

selectReservePercent

public void selectReservePercent(long reservePercent)
                          throws CDFException
Sets the reserve percentage to be used for this variable. This operation is only applicable to compressed z Variables. The Concepts chapter in the CDF User's Guide describes the reserve percentage scheme used by the CDF library.

Parameters:
reservePercent - the reserve percentage to be used

Throws:
CDFException - if a problem occurs setting a reserve percentage

confirmReservePercent

public long confirmReservePercent()
                           throws CDFException
Gets the reserve percentage set for this variable. This operation is only applicable to compressed z Variables.

Returns:
the reserve percentage set for this variable

Throws:
CDFException - if a problem occurs getting the reserve percentage

confirmPadValue

public long confirmPadValue()
                     throws CDFException
Checks the existence of an explicitly specified pad value for the current z variable. If an explicit pad value has not been specified, the informational status code NO_PADVALUE_SPECIFIED is returned. Otherwise, CDF_OK is returned.

Returns:
Existence of pad value. If no pad value is specified for this variable, NO_PADVALUE_SPECIFIED is returned. If a pad value has been specified, then CDF_OK is returned.

Throws:
CDFException - if a problem occurs checking the existence of pad value.

getAllocatedFrom

public long getAllocatedFrom(long recNum)
                      throws CDFException
Inquires the next allocated record at or after a given record for this variable.

Parameters:
recNum - The record number at which to begin searching for the next allocated record. If this record exists, it will be considered the next allocated record.

Returns:
the number of the next allocated record

Throws:
CDFException - if a problem occurs getting the number of the next allocated record

getAllocatedTo

public long getAllocatedTo(long firstRec)
                    throws CDFException
Inquires the last allocated record (before the next unallocated record) at or after a given record for this variable.

Parameters:
firstRec - the record number at which to begin searching for the last allocated record

Returns:
the number of the last allocated record

Throws:
CDFException - if a problem occurs getting the number of the last allocated record

updateDataSpec

public void updateDataSpec(long dataType,
                           long numElements)
                    throws CDFException
Update the data specification (data type and number of elements) of the variable.

Throws:
CDFException

getAttributes

public java.util.Vector getAttributes()
Returns the variable attributes that are associated with this variable.

     The following example describes how to retrieve all the variable
     attributes that are associated with a particular variable.

        Variable v = cdf.getVariable("myVariable");
        Vector   attrs = v.getAttributes();
        if (attrs.size() > 0) {
            for (Enumeration e=attrs.elements(); e.hasMoreElements();) {
                 Attribute a = (Attribute) e.nextElement();
                 // manipulate the attribute
            }
        }
 

Returns:
Returns the variable attributes that are associated with this variable.