Data Input

The data input commands include: Character Read, Matrix Read, Clipboard Read, Data SQL, Data ODBC, Username Password, and Data_XML.

The Data_Read() command has been deprecated now since the Matrix_Read() and Character_Read() commands allow for inputting data into ACON with more flexibility over how many columns of data are read.

Auxiliary Data_Read() commands: Data_Conversion, Missing_Values, On_Missing_Value, On_Null_Value and Data_Format have also been deprecated.

Reading Data

Before you can plot any data using the graphics commands, the data which you want to plot must be read from your data files (unless the data is "created" within ACON). The 3 commands by which data is read into ACON are:

• Data_SQL(...) - for reading Oracle SQL databases
• Matrix_Read(...) - for reading ASCII files into a numeric matrix.
• Character_Read(...) - for reading ASCII files into a character matrix.

The Matrix_Read() command lets you read an entire ASCII data file into a numeric matrix. This implies that to use this data, subsequent graphic commands will be issued with this matrix (or part of it) as the data source.

Note that only columns of data which contain numeric data (which can be read successfully) will be read into memory. Character fields will be ignored. Matrix_Read() assumes that the same number of data columns exist through out the entire file, that there are no missing values, and that 0´s (or some other number) are used to indicate missing data (rather than blank entries).

The Character_Read() command lets you read an entire ASCII data file into a character matrix. Note that the graphic commands [Draw_Text() excepted] require data in numeric format. There are functions available to convert character data to/from numeric format.

ASCII Text Files

Character Read

This command is used to specify the name of the text file to read containing the user´s data. The file is read and converted into a character matrix in memory. The character matrix is then available to be manipulated. Note that for simplified manipulation of the data subsequently, the data should be aligned with specific columns.

A subset of the columns may be converted by including a list of column numbers to read.

There is 2 or more parameters:

file name - the name of the data file to read.

variable name - the name of the data variable into which the data will be saved.

column numbers - the optional list of column numbers to actually convert.

Character_Read("file name","variable name"[,column numbers]);

Character_Read("MyDataFile","Data",1 3 2 6); /* convert the 1st 3rd 2nd and 6th columns only */

See the filled arrows example.

Matrix Read

This command is used to specify the name of the data (text) file to read containing the user´s numeric data. The file is read and converted into a numeric matrix in memory. Each field in the file is converted into a column of data in the matrix. Fields in the data file are recognized as text separated by either a blank, a tab character, comma, or forward slash. Adjacent tab characters, or adjacent commas are interpreted as an empty field and are converted to 0. "Bad" values are converted to NAN (not a number) values or infinity. The data matrix is then available to be manipulated. The file must have the same number of columns of data for all records (and values for each datum if the separator is a blank).

The 1st record may be treated as a header record and removed from the saved data. When the 1st record is parsed, the record is treated as a header record when at least half of the fields contain an alpha character (except for "E"s, which occur in numeric data when represented using exponential notation).

A subset of the fields may be converted by including a list of field numbers to convert.

There is 2 or more parameters:

file name - the name of the data file to read.

variable name - the name of the data variable into which the data will be saved.

header option - the optional flag indicating how to treat the 1st record in the file

(-1 = ignore the 1st record in the file,

0 = parse the 1st record to determine if it is a header record and should be ignored,

1 = include the 1st record in the output data). The default is 0.

field numbers - the optional list of field numbers to actually convert.

Matrix_Read("file name","variable name"[,header option,field numbers]);

/* convert the 1st 3rd 2nd and 6th fields only */
Matrix_Read("MyDataFile","Data",1 3 2 6);

See the example Filled Arrows

Clipboard Read

This command is used to convert the contents of the clipboard into either a numeric matrix, character matrix, or text string in memory.

With numeric matrices, each field in the file is converted into a column of data in the resultant matrix. Fields in the data file are delimited by either a blank, tab character, or comma, space or forward slash "/". Adjacent tab characters, or adjacent commas are interpreted as an empty field and are converted to 0. "Bad" values are converted to NAN (not a number) values or infinity. The data matrix is then available to be manipulated.

With character matrices the line delimiters are removed from input.

With text strings, all ASCII characters in the clipboard are saved.

There are 2 parameters:

variable name - the name of the data variable into which the data will be saved.

data type - optional type of conversion to perform

(0 = numeric matrix, 1 = character matrix, 2 = text string)

Clipboard_Read("variable name"[data type]);

SQL Data Retrieval

Data SQL

This command is used to specify the Oracle SQL Database user ID, password, and optionally the SQL text to execute to retrieve data from an SQL data base. The data is read into memory, and then available to be plotted.

There are 3 or more parameters:

User Id - a character string providing the Oracle user name.

On some hosts where this may be automatically obtained from the user id, use a Null String.

Password - a character string providing the Oracle user password.

On some hosts where this may be automatically obtained from the user id, use a Null String.

SQL text - an optional text string containing the SQL Plus text to execute.

connection flag - optional flag to indicate that the SQL*Net session should remain connected after execution of this Data_SQL() command. This will reduce the connect time for the next Data_SQL() command (0 = don´t remain connected, 1 = remain connected).

If SQL text is not provided as the 3rd argument to this command, then the SQL text is obtained from the subsequent ACON command input. The commands are treated as SQL text input (using this method) and passed to Oracle for processing until an EXIT; command is encountered.

When a SELECT statement is issued in the SQL text, the variables named in the SELECT statement are created as vector variables in memory (each element corresponding to the i^th entry in the matching data in the SQL table). In the example below, the variables: slong,slat,setno are created.

In recent versions (7.17+), the list of variables selected, is returned as a character vector, as the result of the command execution. This may be used (in your user-defined functions) to automatically handle the returned variables by name.

namelist = Data_SQL (User Id,User Password [,SQL text]);

No ´;´ is needed at the end of the SQL statement. Beware of using ACON reserved words or function names as variable names (ie. len).

The current version has problems with the CHAR field datatype, but not with the VARCHAR datatype.

Alternately this extraction may be performed using "in-line" SQL statements...

The usefulness of passing SQL text as the 2nd argument directly, is that the ACON string functions may be used to dynamically generate the SQL text to execute, thus automating repetitive SQL retrievals.

Data ODBC

UNDER DEVELOPMENT.

This command is used to get data from an existing ODBC data source.

There are no parameters.

Data_ODBC();

Username Password

This command is used to acquire a username and password from a dialog. The password is not easily recognizable when typed. When the user closes the dialog by clicking "OK", the username and password are stored in the built-in variable @username, and @password. This is not secure, as the user is able inspect the contents of these variables.

Username_Password();

This may be used to hide the password in a Data_SQL() cmd.

Get_URL

This command is used to read the contents of a Uniform Resource Locator (URL) into memory. The contents returned by the function as a character string.

There is 1 parameter:

file name - the name of the URL to retrieve.

string = Get_URL("file name");

Data_XML

This command is used to read the XML contents of a Uniform Resource Locator (URL) into memory. Any XML tagged information in the file will be parsed, and variables created to store the XML fields. The field contents are flattened so as to return one row per highest order element. During flattening, some XML structures may result in a different sized variable contents. A list of variables created is returned by the function.

There is 1 parameter:

file name - the name of the URL to retrieve.

Data_XML("file name");