GDL Data I/O Add-On

GDL Data I/O

The GDL Data In/Out Add-On allows you to access a simple kind of database by using GDL commands.
Otherwise this Add-On is similar to the GDL Text In/Out Add-On.

Description of Database


The database is a text file in which the records are stored in separate lines. The database can be queried and modified based on a single key.
The key and the other items are separated by a character (specified in the OPEN command).

The length of the lines does not need to be the same and even the number of columns in the records may be different.

If a database is open for writing then there should be enough space beside the database file for duplicating the whole file.

Opening and closing a database may be time consuming, so consecutive closing and opening of a database should be avoided.

Large databases (with more than some hundred thousand records) should be ordered by the key values.

A database can be opened, queried, modified and closed by this Add-On using the OPEN, INPUT, OUTPUT and CLOSE GDL commands.

Opening a Database

channel = OPEN (filter, filename, paramstring)


Opens the database. If the database file is to be opened for modification and the file does not exist, it creates a new file.
If the database file is to be opened for reading and the file does not exist, an error message is displayed.


Its return value is a positive integer that will identify the specific database.
This value will be the database’s future reference number.

If the database is opened before open command, it will generate a channel number only.

filter: the internal name of the Add-On, in this case “DATA”

filename: the name of the database file to be opened

paramstring: add-on specific parameter, contains separator characters and file opening mode parameters

The paramstring may contain the following:

SEPARATOR: 
after the keyword between single quotation marks (”) you can define a character that you want to use
in your text file (both in case of writing and reading) for the separation of data fields.
A special case is the tabulator character (‘t’).
MODE: 
after the keyword the mode of opening has to follow. There are three modes of opening:
  • RO (read only)

  • WA (read, append/modify)

  • WO (overwrite) Empties the database if exists.

DIALOG: 
the ‘filename’ parameter is working as a file-identifier, otherwise it is a full-path-name.
The file-identifier is a simple string, which will be matched to an existing file by the Add-On during a standard ‘Open/Save as’ dialog.
This matching is stored by the Add-On and it won’t ask again except when the file is not available any more.
If the open mode is read only, the Add-On will put up an Open dialog to select an existing document.
Otherwise the Add-On put up an alert-dialog to select between the ‘Create’ and ‘Browse’ options:
  • Create: create a new data-file (Save as Dialog).

  • Browse: search an existing data-file (Open dialog)

LIBRARY: 
If the LIBRARY keyword is present in the parameter string, the data file has to be in the loaded library.
Opening data file from the loaded library for reading is possible from all scripts, but writing is only enabled in the parameter, user interface and property scripts.
Available options for files outside of the loaded libraries:

  • Writing from 2D and 3D scripts are enabled
  • Reading data from external files is regarded as non-determinictic actions, see Background Conversion.

Always put a comma (,) between the components of paramstring.

If you use keywords that don’t exist, if the separator characters given are wrong or if there is nothing in the parameter string,
the extension will use the default settings: "SEPARATOR = 't', MODE = RO"

Example:

ch1 = OPEN ("DATA", "file1",
        "SEPARATOR=';', MODE = RO, DIALOG")
ch2 = OPEN ("DATA", "file2", "")
ch3 = OPEN ("DATA", "newfile",
        "SEPARATOR = 't', MODE = WA")

Reading Values from Database

INPUT (channel, recordID, fieldID, var1 [, var2, ...])

Queries the database based on the key value.


If it finds the record, it reads items from the record starting from the given column
and puts the read values into the parameters in sequence.


In the parameter list there has to be at least one value.
The values can be of numeric or string type independently of the parameter type defined for them.
The return value is the number of successfully read values.


If there are more parameters than values, the parameters without corresponding values will be set to zero.
In case of empty columns (i.e. if there is nothing between the separator characters) the parameters will be set to zero.

If it finds no record it returns (-1).

channel: channel value, used to identify the connection.

recordID: key value (numeric or string).

fieldID: 
the column number in the given record (the smallest number,
1 refers to the item after the key value).

vari: variables to receive the read record items.

Example:

! input of three values from the first column of the first row
nr = INPUT (ch1, "key1", 1, v1, v2, v3)

PRINT nr, v1, v2, v3

Writing Values into Database

OUTPUT channel, recordID, fieldID, expr1 [, expr2, ...]


In case of record creation or modification, it sets the record belonging to the given key value.
The record will contain the given values in the same sequence as they appear in the command. The values can be of numeric or string type.
There has to be at least one expression.


In case of deletion the record belonging to the given key value is removed from the database.
The expression values are ignored, however at least one should be specified.


Modifying data files loaded with the library is only enabled in the parameter, user interface and property scripts.

recordID: key value (numeric or string)

fieldID: flag: specify 0 (or <= 0) to delete a record, specify 1 (or > 0) to create or modify a record

expri: new item values of the found or new record. In case of deletion these values are ignored

Example:

string = "Date: 19.01.1996"
a = 1.5
OUTPUT ch2, "keyA", 1, "New record"
OUTPUT ch2, "keyA", 1, "Modified record"
OUTPUT ch2, "keyA", 0, 0 ! deletes the record
OUTPUT ch2, "keyB", 1, a, string

Closing Database

CLOSE channel

channel: channel value

Closes the database identified by the channel value.