gsfc.nssdc.cdf

Class Variable

java.lang.Object

gsfc.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, 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_CONVERT_WIDECHAR, 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_, STRING_NOT_UTF8_ENCODING, 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	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.
void	deleteRecordsRenumber(long firstRec, long lastRec) Deletes a range of records from this variable.
void	dumpDataWithFormat(CDFData data) Dump the data, either the variable value or metadata, with the format.
void	dumpDataWithFormat(java.lang.Object data) Dump the data, either the variable value or metadata, with or without the format.
void	dumpDataWithFormat(java.lang.Object data, java.io.PrintWriter outWriter) Dump the data, either the variable value or metadata, with or without the format.
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.lang.Object	getAllRecords() Get all written records, from record number 0 till the last written record number, from this variable.
CDFData	getAllRecordsObject() Get all written records, from record number 0 till the last written record number, from this variable.
java.util.Vector	getAttributes() Returns the variable attributes that are associated with this variable.
java.util.Map	getAttributesandEntries() Returns the variable attributes and their entries that are associated with this variable.
java.util.Map	getAttributesandEntries(boolean encoding) Returns the variable attributes and their entries 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 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	putRecords(long startRec, long recCount, java.lang.Object data) Writes a number of records from the current z 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.
java.util.Map	readVariable() Gets the full variable information, its specification, metadata and data.
java.util.Map	readVariable(boolean encoding, boolean basic, boolean metadata, boolean vardata) Gets the specified variable information: its specification, metadata and data.
java.util.Map	readVariableData() Gets the variable's data.
java.util.Map	readVariableMetaData() Gets the variable's metadata.
java.util.Map	readVariableSpec() Gets the variable's specification.
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_UINT2 - 2-byte, unsigned integer
• CDF_INT4 - 4-byte, signed integer
• CDF_UINT4 - 4-byte, unsigned integer
• CDF_INT8 - 8-byte, signed 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
• CDF_TIME_TT2000 - 8-byte, signed integer

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.

Parameters:

destVar - the destination variable to copy data into

Throws:

CDFException - if there was a problem copying data records 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.

concatenateDataRecords

public void concatenateDataRecords(Variable destVar)
                            throws CDFException

Concatenates this variable's data records to the destination variable.

Parameters:

destVar - the destination variable to copy data records into

Throws:

CDFException - if there was a problem copying data records 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.

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 an entire record (containing 6 elements) from the first record from a variable of data type CDF_INT4:

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

However, if a dimensional variable with all indices being invariant, e.g., 2-dimensional (1x1), the retrieved object will be different. (Since the variable has only one data value per record, it is preferred to be defined as an 0-dim, rather.). The object is not an array, instead, a single Java class item, e.g., Integer, Double, Short, etc. The following example extracts an record from the first record of a variable, 2-dim (1x1), with data type CDF_INT2:

     Variable var = cdf.getVariable("TestVar");
     short data = ((Short) var.getRecord(0L)).shortValue();
 

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:

CDFData object 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:

CDFData object containing the requested data record(s)

Throws:

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

getAllRecordsObject

public CDFData getAllRecordsObject()
                            throws CDFException

Get all written records, from record number 0 till the last written record number, from this variable. The data values read are put into an CDFData object. Note: If this variable has sparse records, then the missing record(s) is filled with FILLVAL (or PAD if FILLVAL does not exist) value.

Returns:

CDFData object containing all data record(s)

Throws:

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

getAllRecords

public java.lang.Object getAllRecords()
                               throws CDFException

Get all written records, from record number 0 till the last written record number, from this variable. The data values read are put into an Object. Note: If this variable has sparse records, then the missing record(s) is filled with FILLVAL (or PAD if FILLVAL does not exist) value.

Returns:

Object containing all 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

readVariable

public java.util.Map readVariable()

Gets the full variable information, its specification, metadata and data. Note: Each metadata/data of epoch type data will be encoded in date/time string.

  Variable v = cdf.getVariable("var1");
  Map var = v.readVariable();
  // Three key-value pairs will be included with keys of as
  // "VarSpec", "VarMetaData", "VarData"

  // Key: "VarSpec" contains variable specification - another Map object
  // These include: keys of "DataType", "NumElements", "NumDims",
  // "DimSizes" and "PadValue".
  System.out.println("  specification: "+var.get("VarSpec")); 

  // Key: "VarMetaData" contains variable attributes - another Map object
  // These include variable attribute name (key) and its entry (value)
  System.out.println("  meta: "+var.get("VarMetaData"));

  // Key: "VarData" has variable data - an object
  System.out.println("  data:"); 
  CDFUtils.printData(var.get("VarData")); 

 

Returns:

A Map object that contains the full variable information.

readVariableSpec

public java.util.Map readVariableSpec()

Gets the variable's specification.

Returns:

A Map object that contains the variable's specification with the key "VarSpec". The value is another Map object.

readVariableMetaData

public java.util.Map readVariableMetaData()

Gets the variable's metadata.

Returns:

A Map object that contains the variable's metadata with the key "VarMetaData". The value is another Map object if it has metadata.

readVariableData

public java.util.Map readVariableData()

Gets the variable's data.

Returns:

A Map object that contains the variable's specification with the key "VarData".

readVariable

public java.util.Map readVariable(boolean encoding,
                                  boolean basic,
                                  boolean metadata,
                                  boolean vardata)

Gets the specified variable information: its specification, metadata and data.

  Variable v = cdf.getVariable("var1");
  Map var = v.readVariable(true, true, true, true);
  // Three key-value pairs might be included with keys of as
  // "VarSpec" and "VarMetaData" and/or "VarData" if there are data.

  // Key: "VarSpec" contains variable specification - another Map object
  // These include: keys of "DataType", "NumElements", "NumDims",
  // "DimSizes" and "PadValue".
  System.out.println("  specification: "+var.get("VarSpec")); 

  // Key: "VarMetaData" contains variable attributes - another Map object
  // These include variable attribute name (key) and its entry (value)
  System.out.println("  meta: "+var.get("VarMetaData"));

  // Key: "VarData" has variable data - an object
  System.out.println("  data:"); 
  CDFUtils.printData(var.get("VarData")); 

 

Parameters:

encoding - A true/false flag indicates whether to encode epoch data type from metadata to date/time string.

basic - A true/false flag indicates whether to return the specification of the variable

metadata - A true/false flag indicates whether to return the metadata from the variable

vardata - true/false flag indicates whether to return the data from the variable

Returns:

A Map object that contains the requested variable information.

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}, testData);
 

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}, testData);       
 

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

putRecords

public CDFData putRecords(long startRec,
                          long recCount,
                          java.lang.Object data)
                   throws CDFException

Writes a number of records from the current z variable. The values are written from the starting record number. 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 three records to the variable as the first, second, and third record:

     long [][][] testData = {{{10,20},{30,40},{50, 60}},
                             {{15,25},{45,55},{75, 85}}
                             {{90,95},{96,97},{2147483648L,4294967295L}}
                             };
     testData.putRecords (0L, 3L, testData);
 

Parameters:

startRec - the starting record number at which data write begins

recCount - the number of records to write

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.

Overrides:

toString in class java.lang.Object

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. While non-sparse variable records after the last deleted record will be renumbered, the sparse variable records will not.

Parameters:

firstRec - the first record to be deleted

lastRec - the last record to be deleted

Throws:

CDFException - if a problem occurs deleting records

deleteRecordsRenumber

public void deleteRecordsRenumber(long firstRec,
                                  long lastRec)
                           throws CDFException

Deletes a range of records from this variable. All records after the last deleted record are renumbered for both the sparse or non-sparse variable after the deletion.

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.

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.

Throws:

CDFException - if a problem occurs checking the existence of the pad value Note: The getPadValue() method will return a pad value, whether it is the user defined or the default.

getPadValue

public java.lang.Object getPadValue()
                             throws CDFException

Gets the pad value for this variable.

Returns:

the pad value set for this variable

Throws:

CDFException - if a problem occurs reading the pad value

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. Note: for NO_PADVALUE_SPECIFIED, getPadValue method will return the default 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.

Parameters:

dataType - the data type of the entry data

numElements - the number of elements fo the entry data

Throws:

CDFException - An exception is thrown if the operation fails

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.

getAttributesandEntries

public java.util.Map getAttributesandEntries()

Returns the variable attributes and their entries that are associated with this variable.

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

       Variable v = cdf.getVariable("myVariable");
       Map vaes = v.getAttributesandEntries();
       if (vaes != null) {
         for (Object key : vaes.keySet()) {
           System.oit.println("Attribute:"+key+" entry:"+vaes.get(key));
         }
       }
 

Note: Each attribute's entry, an object, can be a single data or an array of values. CDF Epoch type data will be encoded in date/time string.

Returns:

Returns a Map object that contains variable attribute names as keys and entries as values that are associated with this variable. All keys and values are in object type. If there is no attribute, then null is returned;

getAttributesandEntries

public java.util.Map getAttributesandEntries(boolean encoding)

Returns the variable attributes and their entries that are associated with this variable.

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

       Variable v = cdf.getVariable("myVariable");
       Map vaes = v.getAttributesandEntries(true);
       if (vaes != null) {
         for (Object key : vaes.keySet()) {
           System.oit.println("Attribute:"+key+" entry:"+vaes.get(key));
         }
       }
 

Note: Each attribute's entry, an object, can be a single data or an array of values.

Parameters:

encoding - A true/false flag indicates whether to encode epoch type data to date/time string.

Returns:

Returns a Map object that contains variable attribute names as keys and entries as values that are associated with this variable. All keys and values are in object type. If there is no attribute, then null is returned;

dumpDataWithFormat

public void dumpDataWithFormat(java.lang.Object data)

Dump the data, either the variable value or metadata, with or without the format. The format comes from the FORMAT variable attribute.

Parameters:

data - An object, likely an attribute entry, for output

dumpDataWithFormat

public void dumpDataWithFormat(java.lang.Object data,
                               java.io.PrintWriter outWriter)

Dump the data, either the variable value or metadata, with or without the format. The format comes from the FORMAT variable attribute.

Parameters:

data - An object, likely an attribute entry, for output

outWriter - the print writer to which formatted representations of the object/data is printed as a text-output stream

dumpDataWithFormat

public void dumpDataWithFormat(CDFData data)

Dump the data, either the variable value or metadata, with the format. The format comes from the FORMAT variable attribute.

Parameters:

data - A CDFData object, likely variable data, for output