dataopen#

Purpose#

Opens a dataset.

Format#

fh = dataopen(filename, mode)#

Parameters:

filename (string) – name of data file.

mode (string) –

containing one of the following:

read	Open file for read only.
append	Open file for append. The file pointer will start at the end of the file to add new rows.
update	Open file for update. Allows reading and writing. The file pointer will start at the first row.

Returns:

fh (scalar) – file handle.

Examples#

Read from a GAUSS dataset#

// Create a file name with full path
file_name = getGAUSSHome("examples/credit.dat");

// Open file handle to dataset and assign it to 'fh'
fh = dataopen(file_name, "read");

// Read 100 rows from the dataset into the variable 'y'
y = readr(fh, 100);

// Close file handle
ret = close(fh);

Write to a GAUSS dataset#

// Create variable names for dataset
var_names = "alpha" $| "beta";

// Create dataset containing 2 variables with 5 observations all equal to 1
x = ones(5, 2);
call saved(x, "my_ones.dat", var_names);

// Open file handle to dataset and assign it to 'fh'
fh = dataopen("my_ones.dat", "update");

// Write to the first row
y = { 17 21 };
call writer(fh, y);

// Close file handle
ret = close(fh);

// Load all contents of dataset
new_x = loadd("my_ones.dat");

After the code above, new_x should be equal to:

Remarks#

1. The file must exist before it can be opened with the dataopen() command (to create a new file, see datacreate() or datasave()).

2. The file handle returned by dataopen() is a scalar containing a positive integer value that uniquely identifies each file. This value is assigned by GAUSS when the create, datacreate(), datacreatecomplex(), open or dataopen() commands are executed. The file handle is used to reference the file in the commands readr() and writer(). If dataopen() fails, it returns a -1.

3. A file can be opened simultaneously under more than one handle. If the value that is in the file handle when the dataopen() command begins to execute matches that of an already open file, the process will be aborted and a File already open error message will be given. This gives you some protection against opening a second file with the same handle as a currently open file. If this happens, you would no longer be able to access the first file.

4. It is important to set unused file handles to zero because both dataopen() and datacreate() check the value that is in a file handle to see if it matches that of an open file before they proceed with the process of opening a file. You may set unused file handles to zero with the close or closeall commands.

5. If filename does not have an extension, dataopen() appends a .dat extension before searching for the file. If the file is an .fmt matrix file, the extension must be explicitly given. If no path information is included, then dataopen() searches for the file in the current directory.

6. Files opened in read mode cannot be written to. The pointer is set to the beginning of the file and the writer() function is disabled for files opened in this way. This is the only mode available for matrix files (.fmt), which are always written in one piece with the save command.

7. Files opened in append mode cannot be read. The pointer is set to the end of the file so that a subsequent write to the file with the writer() function will add data to the end of the file without overwriting any of the existing data in the file. The readr() function is disabled for files opened in this way. This mode is used to add additional rows to the end of a file.

8. Files opened in update mode can be read from and written to. The pointer is set to the beginning of the file. This mode is used to make changes in a file.

The supported dataset types are .dat, .h5, .fmt.

For HDF5 files, the dataset must include schema and both file name and dataset name must be provided, e.g.

glm("h5://C:/gauss/examples/testdata.h5/mydata").

Source#

datafile.src