There is no limit for the number of data that can be stored in a single record for HEC-DSS version 7, however, memory management and the ability to use the record without issues, such as in a Java table, suggests reasonable limits be used. For example, if you were computing a dataset that could be represented in a table with 1,000 columns and 10,000 rows, it would be far better to store as 1,000 separate paired data records (with 10,000 rows each), rather than a single paired data record of 1,000 by 10,000.

Paired Data records of 1,000 by 10,000 have been tested with DSS-7, but that size will probably exceed the available memory in most applications.) The Hec Data Table functions can display many separate datasets in a single table (or plot), so typically there is no need to have large paired data sets stored as one record. Regardless, sometimes large paired datasets are needed and HEC-DSS version 7 has functions to accomidate this.


In HEC-DSS version 7, you can read or write a block of a paired dataset, without having to read or write the entire record. For example, you may want to read or write a block that is for columns 35 to 42 and rows 541 to 550. DSS will read or write only those values and return (or store) that subset, which will be 8 rows by 10 columns for this example.

The location on disk of those values will be computed and only those values will be read (or written). This saves resources considerably without having to do a large allocation of memory or read a large segment from disk.


If you have a program that computes where paired data values are computed in separate iterations (i.e., the whole dataset is not computed at one time), then space for that record is "allocated" prior writing data to it. To allocate space, a PairedDataContainer is filled out with everything except for the coordinate arrays (the columns in the table). The number of rows and columns, labels, units, etc., for each column, and the complete ordinate array (first column of the table) need to be given for the allocation.


To allocate space for a paired dataset, use the PairedDataContainer "allocateSpace" method and then write the container to disk. To write or read only a segment of the record, specify the startingCurve, endingCurve, startingOrdinate, and endingOrdinate in the PairedDataContainer.

Note: the first curve and first ordinate are 1, not 0. A zero in these variables indicates to ignore them. If you want to write an entire single curve, set the startingOrdinate and endingOrdinate to zero. Setting all 4 variables to zero, indicates that you are writing the entire dataset.
Functions for PairedDataContainers with Large Datasets

Functions for PairDataContainers with Large Data 

public void allocateSpace(double xOrdinates\[\], int numberCurves)
public void setStartingEndingCurve(int startingCurve, int endingCurve)
public void setStartingEndingOrdinage(int startingOrdinate, int endingOrdinate)
public void setXOrdinates(double xOrdinates\[\])
public void setYOrdinates(double yOrdinates\[\]\[\])
JAVA

For example:

	//  Allocate space on disk 
PairedDataContainer pdc = new PairedDataContainer();	
		pdc.setName("/Basin/Location/Stage-Damage///Test/");
		double xOrdinates[] = new double[500];		
		//  (define ordinates)
//  Set the write to allocate space, with 500 ordinances, 10 curves
//  Y ordinates will be set to 0 if not defined.
		pdc.allocateSpace(xOrdinates, 10);
		HecPairedData dssPairedData = new HecPairedData();
		//  Write ordinates and allocate space		
		int status = dssPairedData.write(pdc);

		...

		//  Write a single value in the record
		PairedDataContainer pdc = new PairedDataContainer();
		pdc.setName("/Basin/Location/Stage-Damage///Test/");
		//  Because the record already has been allocated and
		//  the start/end curve and ordinates are defined,
		//  numberOrdinates and numberCurves is not needed.		
		//  First curve is #1, not #0 (by convention)
pdc.setStartingEndingCurve(4, 4);
		pdc.setStartingEndingOrdinage(50, 55);
		//  yOrdinates[numberCurves][numberOrdinates]
//  and need to match start/ending ordinates and curves
		double yOrdinates[][] = new double[1][1];
		yOrdinates[0][0] = 123.456;
		pdc.setYOrdinates(yOrdinates);
		HecPairedData dssPairedData = new HecPairedData();
		status = dssPairedData.write(pdc);
JAVA


Example: Writing individual paired data curves

// This example pre-allocates space for a paired data record so that individual curves can be written at a later time. 
// Curves are then read and tabulated and plotted.
import java.util.Vector;
import javax.swing.UIManager;
import hec.dataTable.HecDataTableFrame;
import hec.gfx2d.G2dDialog;
import hec.heclib.dss.*;
import hec.io.DataContainer;
import hec.io.PairedDataContainer;

//  Write a family of curves by allocating space, then writing one curve at a time
//
public class ExamplePairedData3 {

	public static void main (String args[])  {

		try {
			javax.swing.UIManager.setLookAndFeel(UIManager.getSystemLookAndFeelClassName());
		}
		catch (Exception ignore) {}

		//  Use the same DSS file for all reads and writes
		HecDataManager.setDefaultDSSFileName("C:/temp/Example7.dss");		
		DSSPathname path = new DSSPathname("/Basin/Location/Stage-Damage///Test/");

		//  Gen up the data
		PairedDataContainer pdc1 = new PairedDataContainer();	
		pdc1.setName(path.pathname());
		//  Allocate space for 500 rows for a family of 10 curves
		//  Gen up the ordinates
		double xOrdinates[] = new double[500];
		for (int i=0; i<xOrdinates.length; i++) {
			xOrdinates[i] = (double)(i + 1) * 2;
		}	
		//  Set the write to allocate space
		pdc1.allocateSpace(xOrdinates, 10);
		pdc1.setXUnits("Feet");
		pdc1.setXType("Linear");
		pdc1.setYUnits("Dollars");
		pdc1.setYType("Linear");
		pdc1.setStoreAsDoubles(true);
						
		HecPairedData dssPairedData1 = new HecPairedData();
		int status = dssPairedData1.write(pdc1);
		dssPairedData1.done();		
		if (status != 0) return;
		
		//  Now write each of the 10 curves separately 
		for (int j=0; j<10; j++) {
			PairedDataContainer pdc = new PairedDataContainer();
			pdc.setName(path.pathname());
			double yOrdinates[][] = new double[1][500];
			for (int i=0; i<500; i++) {
				yOrdinates[0][i] = ((double)(i + 1) * 100.0) + (double)((j + 1) * 3000);
			}
			//  First curve is #1, not #0 (by convention)
			pdc.setStartingEndingCurve(j+1, j+1);
			pdc.setYOrdinates(yOrdinates);
			HecPairedData dssPairedData = new HecPairedData();
			status = dssPairedData.write(pdc);
			dssPairedData.done();		
			if (status != 0) return;
		}

		//  Read curve 4 and 5 and tabulate
		PairedDataContainer pdc3 = new PairedDataContainer();	
		pdc3.setName(path.pathname());
		pdc3.setStartingEndingCurve(4, 5);
		HecPairedData dssPairedData3 = new HecPairedData();
		status = dssPairedData3.read(pdc3);		
		dssPairedData3.done();		
		if (status != 0) return;
		//  Show in a table
		HecDataTableFrame table3 = new HecDataTableFrame(null);
		table3.setData(pdc3);
		table3.setVisible(true);

		//  Read all curves and plot
		PairedDataContainer pdc4 = new PairedDataContainer();	
		pdc4.setName(path.pathname());
		HecPairedData dssPairedData4 = new HecPairedData();
		status = dssPairedData4.read(pdc4);
		dssPairedData4.done();		
		if (status != 0) return;
		//  Show in a plot
		Vector<DataContainer> v = new Vector<DataContainer>();
		v.add(pdc4);
		hec.gfx2d.G2dDialog plot =  new G2dDialog(null, "My Plot", false, v);
		plot.setVisible(true);

		HecDataManager.closeAllFiles();  //  Only at the end of the program
	}
}
JAVA




Example: Reading and writing a block from a paired dataset

This example demonstrates reading a block from a paired dataset.  The block is specified by a starting and ending curve (column) and a starting and ending ordinate (row).  The values are changed to negative and then written back to the same dataset.
import javax.swing.UIManager;
import hec.dataTable.HecDataTableFrame;
import hec.heclib.dss.*;
import hec.io.PairedDataContainer;

//  Read and write a block of a paired data record
//
public class ExamplePairedData4 {

	public static void main (String args[])  {

		try {
			javax.swing.UIManager.setLookAndFeel(UIManager.getSystemLookAndFeelClassName());
		}
		catch (Exception ignore) {}

		//  Use the same DSS file for all reads and writes
		HecDataManager.setDefaultDSSFileName("C:/temp/Example7.dss");		
		DSSPathname path = new DSSPathname("/Basin/Location/Stage-Damage///Test 4/");

		//  Gen up a full dataset
		PairedDataContainer pdc1 = new PairedDataContainer();	
		pdc1.setName(path.pathname());
		//  write a data set for 500 rows for a family of 10 curves
		//  Gen up the ordinates
		double xOrdinates[] = new double[500];
		double yOrdinates[][] = new double[10][500];
		for (int i=0; i<xOrdinates.length; i++) {
			xOrdinates[i] = (double)(i + 1) * 2;
			for (int j=0; j<10; j++) {
				yOrdinates[j][i] = ((double)(i + 1) * 100.0) + (double)((j + 1) * 3000);
			}	
		}
		//  Set the arrays
		pdc1.setValues(xOrdinates, yOrdinates);
		pdc1.setXUnits("Feet");
		pdc1.setXType("Linear");
		pdc1.setYUnits("Dollars");
		pdc1.setYType("Linear");
		HecPairedData dssPairedData1 = new HecPairedData();
		int status = dssPairedData1.write(pdc1);
		dssPairedData1.done();		
		if (status != 0) return;

		//  Read a block and tabulate
		PairedDataContainer pdc3 = new PairedDataContainer();	
		pdc3.setName(path.pathname());
		pdc3.setStartingEndingCurve(5, 9);
		pdc3.setStartingEndingOrdinage(2, 5);
		HecPairedData dssPairedData3 = new HecPairedData();
		status = dssPairedData3.read(pdc3);			
		if (status != 0) return;
		//  Show in a table
		HecDataTableFrame table3 = new HecDataTableFrame(null);
		table3.setData(pdc3);
		table3.setVisible(true);

		//  Change the numbers to negative and store
		double xords[] = pdc3.getXOridnates();
		double yords[][] = pdc3.getYOridnates();
		for (int i=0; i<xords.length; i++) {
			for (int j=0; j<yords[0].length; j++) {
				yords[j][i] = -yords[j][i];
			}
		}	
		//  pdc3 retains the starting / ending curves and ordinates
		pdc3.setXOrdinates(xords);
		pdc3.setYOrdinates(yords);
		status = dssPairedData3.write(pdc3);		
		dssPairedData3.done();		
		if (status != 0) return;	

		//  Read all curves and show in table
		PairedDataContainer pdc4 = new PairedDataContainer();	
		pdc4.setName(path.pathname());
		HecPairedData dssPairedData4 = new HecPairedData();
		status = dssPairedData4.read(pdc4);
		dssPairedData4.done();		
		if (status != 0) return;
		//  Show in a plot
		HecDataTableFrame table4 = new HecDataTableFrame(null);
		table4.setData(pdc4);
		table4.setVisible(true);

		HecDataManager.closeAllFiles();  //  Only at the end of the program
	}
}
JAVA