Data Import and Export#

General data loading#

Note

loadd and saved are recommended for most cases when working with the following file types:

  • GAUSS, SAS, Stata and SPSS datasets.

  • CSV and Excel files with variable names in the first row.

getHeaders

Returns the variable names from a dataset as a string array.

loadd

Loads data into a GAUSS dataframe. The supported dataset types are CSV, Excel (XLS, XLSX), HDF5, GAUSS Matrix (FMT), GAUSS Dataset (DAT), Stata (DTA) and SAS (SAS7BDAT, SAS7BCAT).

saved

Writes a matrix or dataframe in memory to a dataset in a specified format.

CSV and delimited text files#

csvReadM

Reads numeric data from a CSV file into a GAUSS matrix.

csvReadSA

Reads data from a CSV file into a GAUSS string array.

csvWriteM

Write the contents of a GAUSS matrix to a CSV file.

Spreadsheets (Excel files)#

xlsGetSheetCount

Returns the number of sheets in an Excel® spreadsheet.

xlsGetSheetSize

Returns the size (rows and columns) of a specified sheet in an Excel® spreadsheet.

xlsGetSheetTypes

Gets the cell format types of a row in an Excel® spreadsheet.

xlsMakeRange

Builds an Excel® range string from a row/column pair.

xlsReadM

Reads from an Excel® spreadsheet into a GAUSS matrix.

xlsReadSA

Reads from an Excel® spreadsheet into a GAUSS string array.

xlsWrite

Writes a GAUSS matrix, string, or string array to an Excel® spreadsheet.

HDF 5 files#

h5create

Create a HDF5 dataset (.h5).

h5open

Open a HDF5 file.

h5read

Reads data from a HDF5 file (.h5) into a GAUSS matrix.

h5readAttribute

Read attributes from a HDF5 file into GAUSS.

h5write

Writes a GAUSS matrix to a HDF5 file.

GAUSS Data Sets#

These are the main functions to use for loading and saving GAUSS datasets.

loadd

Loads a data set into a GAUSS dataframe.

saved

Saves matrices or dataframes to a variety of dataset types.

The following functions use file handles which enable reading and writing partial chunks of a dataset.

close

Closes an open data set (.dat file).

closeall

Closes all open data sets.

datacreate

Creates a file handle to a new, empty GAUSS data set.

dataopen

Opens a file handle to a GAUSS data set.

eof

Tests for end of file.

getnr

Computes number of rows to read per iteration for a program that reads data from a disk file in a loop.

getnrmt

Computes number of rows to read per iteration for a program that reads data from a disk file in a loop.

readr

Reads rows from open data set.

seekr

Moves pointer to specified location in open data set.

tempname

Creates a temporary file with a unique name.

typef

Returns the element size (2, 4 or 8 bytes) of data in open data set.

writer

Writes matrix to a GAUSS dataset using open file handle.

Databases#

Database Setup#

dbAddDatabase

Adds a database to the list of database connections using the driver type or a connection URL.

dbGetDrivers

Returns a list of available database drivers.

dbIsDriverAvailable

Returns 1 if a specified database driver is available.

dbRemoveDatabase

Removes a database connection from the list of open database connections. Frees all related resources.

Database Properties#

dbGetConnectOptions

Returns the connection options string used for a database connection.

dbGetDatabaseName

Returns the name of the database.

dbGetDriverName

Returns the name of the connection’s database driver.

dbGetHostName

Returns the database connection’s host name.

dbGetPassword

Returns a connection’s password.

dbGetNumericalPrecPolicy

Returns the default numerical precision policy for a specified database connection.

dbGetPort

Returns the database connection’s port number if it has been set.

dbIsOpen

Reports whether a specified database connection is open.

dbIsValid

Reports whether a specified database connection has a valid driver.

dbSetConnectOptions

Sets database-specific options.

dbSetDatabaseName

Sets the connection’s database name to name.

dbSetHostName

Sets the specified database connection’s host name.

dbSetNumericalPrecPolicy

Sets the default numerical precision policy used by queries created on this database connection.

dbSetPassword

Sets the database connection’s password.

dbSetPort

Sets the specified database connection’s port number.

Database Information#

dbGetPrimaryIndex

Returns the primary index for the specified table.

dbGetTableHeaders

Returns a string array populated with the names of all the fields in a specified table (or view).

dbGetTables

Returns the database’s tables, system tables and views.

dbHasFeature

Returns a 1 if the database supports the specified feature.

Database Errors#

dbGetLastErrorNum

Returns numerical information about the last error that occurred on the database.

dbGetLastErrorText

Returns text information about the last error that occurred on the database.

dbIsOpenError

Reports whether an error occurred while attempting to open the database connection.

dbQueryGetLastErrorNum

Returns numerical error information about the last error that occurred (if any) with the last executed query.

dbQueryGetLastErrorText

Returns text error information about the last error that occurred (if any) with the last executed query.

Database Connect#

dbClose

Closes a database connection and destroys any remaining queries.

dbOpen

Opens a specified database connection using the current connection values.

Database Transaction#

dbCommit

Commits a transaction to the database if the driver supports transactions and a dbTransaction() has been started.

dbCreateQuery

Process an SQL statement and prepare a query.

dbExecQuery

Executes an SQL statement and creates a query.

dbExecQueries

Executes an SQL statement and creates a query for multiple rows of data in one function call.

dbRollback

Rolls back a transaction on the database.

dbTransaction

Begins a transaction on the database.

Query Building#

dbQueryBindValue

Set the placeholder placeholder to be bound to value val in the prepared statement.

dbQueryGetBoundValue

Returns the value for a placeholder in a query.

dbQueryGetBoundValues

Returns an Nx2 string array containing the placeholders and their corresponding values in a query.

dbQueryExecPrepared

Executes a previously created and prepared query.

dbQueryPrepare

Prepares a SQL query for execution.

Query Manipulation#

dbQueryClear

Clears the result set and releases any resources held by the query. Sets the query state to inactive.

dbQueryFinish

Instructs the database driver that no more data will be fetched from this query until it is re-executed.

Query Information#

dbQueryCols

Returns the number of fields in the record.

dbQueryGetLastInsertID

Returns the object ID of the most recent inserted row if supported by the database.

dbQueryGetLastQuery

Returns the text of the current query being used.

dbQueryGetNumRowsAffected

Reports the number of rows affected by the result’s SQL statement.

dbQueryIsActive

Returns 1 if the query is active.

dbQueryIsForwardOnly

Reports whether you can only scroll forward through a result set.

dbQueryIsNull

Reports whether the current field pointed at by an active query positioned on a valid record is NULL.

dbQueryIsSelect

Reports whether the specified query is a SELECT statement.

dbQueryIsValid

Reports whether the specified query is positioned on a valid record.

dbQueryRows

Returns the size of the result (number of rows returned), or -1 if the size cannot be determined or if the database does not support reporting information about query sizes.

dbQuerySetForwardOnly

Sets forward only mode to forward. If forward is true, only ../dbQuerySeekNext and ../dbQuerySeek with positive values, are allowed for navigating the results.

Query Iteration#

dbQueryGetPosition

Returns the current internal position of the query.

dbQuerySeek

Retrieves the record at a specified position, if available, and positions the query on the retrieved record.

dbQuerySeekFirst

Retrieves the first record in the result, if available, and positions the query on the retrieved record.

dbQuerySeekLast

Retrieves the last record in the result, if available, and positions the query on the retrieved record.

dbQuerySeekNext

Retrieves the next record in the result, if available, and positions the query on the retrieved record.

dbQuerySeekPrevious

Retrieves the previous record in the result, if available, and positions the query on the retrieved record.

Query Data Retrieval#

dbQueryFetchAllM

Returns the result set for the current query as a matrix.

dbQueryFetchAllSA

Returns the result set for the current query as a string array.

dbQueryFetchOneM

Returns a single row as an Nx1 matrix where N is the column count of the SELECT statement.

dbQueryFetchOneSA

Returns a single row as a string vector containing the field information for the current query.

dbQueryGetField

Returns the value of a specified field in the current record.

General text file manipulation#

To read and write data from CSV and delimited text files, see the earlier section.

fcheckerr

Gets the error status of a file.

fclearerr

Gets the error status of a file, then clears it.

fflush

Flushes a file’s output buffer.

fgets

Reads a line of text from a file.

fgetsa

Reads lines of text from a file into a string array.

fgetsat

Reads lines of text from a file into a string array without retaining newlines.

fgetst

Reads a line of text from a file without retaining the newline.

fopen

Opens a file.

fputs

Writes strings to a file.

fputst

Writes strings followed by a newline to a file.

fseek

Positions the file pointer in a file.

fstrerror

Returns an error message explaining the cause of the most recent file I/O error.

ftell

Gets the position of the file pointer in a file.

getf

Loads an ASCII or binary file into a string.

putf

Writes the contents of a string to a file.