5.

11 Database Components
IMPORTANT: OI-15 with Hard Drive option is required for local persistent data storage.
For OI-15 without a Hard Drive or when a Hard Drive malfunctions, data will be stored
temporarily in the system running memory and will be lost if the machine loses power.
Alternatively, OI-15 has the capability to read/write data from/to a remote database.
However, the use of this particular function is rare and application specific. Its use is
therefore restricted within OIB and we will only cover this topic briefly in the pertinent
sections.
DB Connection property is common to all Database Components. It defines the connection
parameters OI will use to communicate with a particular database server. The default
database server supported by OI-15 is PostgreSQL. By default, it communicate with database
oi on local host 127.0.0.1, with user name user and no password. OIB restricts
database server access to local and therefore the editing of hostName setting is disabled. It
can be changed however in a text editor.

5.11.1 Database Write Component

A database write component is for writing tag based information to a specified database table
residing either on the hard drive or in the internal memory of the OI system. If the database
table does not exist, OI will create it based on the information provided before writing any
data.

Creating Database Write Components

Database write buttons can be created in one of two ways. Click on the components menu
and select 'Database' and then 'Database Write'. Alternatively, click on the database write
button icon in the toolbar. Moving down to the the OI builder screen will turn the mouse
pointer into a crosshair. Select a starting location for the button then click and hold the left
mouse button. Drag the crosshair away from its point of origin and release when the
component reaches a desired size. The size of the button in pixels is shown in a variable
display as it is being created.

To make another database write button of the same type, move the crosshair to a different
area of a screen and click again. If you wish to make a duplicate of a recently created button,
click on the chosen component and select 'copy' in the edit menu. Then select 'paste' in the
edit menu.

Setting Database Write Component Properties

name: This is the name of the database write component. It refers to the object on the
screen and it is for identification purposes within the application only.

description: Optional description for this component.

triggerTag: This refers to the tag that will cause data to be written to a row in the
specified database table. Auto-complete feature is enabled for this field for tags that are
already defined in the tag editor. A drop down list is also provided for tag selection.

triggerOnEvent: ZeroToNonZero and AnyChange events are supported.

findRecordTag:

statusTag:

tagList: Here we enter a list of tags seperated by semicolon. Each tag may only appear
once. If multiple occurances are detected, the later occurances will be ignored. At the time of
a triggering event, the values of these tags will be read and written to the specified database
table. The database table will be created when the application starts if it does not exist. The
order and names of the columns in the table will be determined by the order and names of the
tags listed. The data type of the column is determined by the data type of the tag.
If at the time of loading the application, the structure of the list has changed, the structure of
the table will be changed accordingly. In the event of this, OI system will try to modify the
previous data types to best match the new data types. If the conversion is not possible, the
previous data may be lost.
In addition to columns created by database write component based on the user provided tag
list, the following columns are implicitly created and managed by the OI system:
__id__ : internal id column used as the primary key of the table
__oi_store_time__: time at which the OI initiated the writing of the data
__db_store_time__: time at which the database system stores the data
tableName: The name of the database table into which the database write component
would insert data.
tableRowsLimit: The purpose of this property is to prevent the size of the database
tables from exceeding the limits of the storage media. This value determines the maximum
number of the records in the table. When the amount of records exceeds this limit and a new
record is written, the oldest record in the table will be erased. When this number is set to 0,
the amount of records for this table will be limited by tableSizeLimit if specified, or set
automatically based on the actual room in the storage media.
tableSizeLimitMB: Determines the maximum size of the tabel in MB. When the size of
the table exceeds this limit, the oldest record in the table will be erased. Testing available
space is performed every 10 minutes. When the test determines that the table is over-sized,
the oldest 5% of the records are removed. When this number is set to 0, the size of the
table will be limited either by tableRowLimit if specified, or automatically by the actual
room available in the storage media.
To determine when the oldest record will be erased, the lower limit of both tableRowsLimit
and tableSizeLimit is considered. In addition, the oldest records are removed automatically
whenever the storage media is running out of capacity. This can happen when one or more
tables do not have set size limits. When this occurs, the OI system automatically changes the
settings in the tableRowsLimit for all tables which are being written. It detects the actual

number of rows in each table and decreases the amount by 5%. The resulting values is then
used as the new tableRowsLimit. These settings can be edited by the user in the
tableRowsLimit field in the property editor of a database write component. Since these
automatic limits are created internally, these limits must be read from the OI before opening
the application in OIB. The limits do not save themselves to the application automatically.
The actual settings are displayed in the config screen of the OI.
Additionally, due to development in storage technology, the capacity of the hard drive is
getting so large that the amount of the data generated would not come close to the physical
limit of the hard drive within a reasonable time frame. However, because of the performance
concerns for exceptionally large databases, the OI system does impose an internal limit on
the size of database tables. This actual limit will be displayed in the config screen of the OI.
printToPrinterOnPort: This selection enables the printing via physical interfaces, in
ASCII format, of each record when it is written. The individual components are delimited by
the printColumnSeparator (see next section). The following ports are available: LPT1-3,
COM1-4, USB1-4, USBToSerial1-4. Note that all these ports may not be physically present
in every OI system type. If the Disabled option is selected, the record will not be printed.
printColumnSeparator: This specifies the delimiter used for separating the data sent to
the print port. By default, the system uses comma.

printCharsPerLine: This determines the number of characters to be printed for each

line. This option is used only when printToPrinterOnPort is not disabled. By default, the
system uses 80.

printHeader: When this option is enabled, the column names will also be printed on its
own line before the data.

5.11.2 Database Read Component

The purpose of the Database Read component is to retrieve data from the database table and
make it available through OI's tag based system. The data can then be used for on screen
components, and/or be used in conjunction with the tagCopy component to make the data
available to other control devices such as PLC.

Database Addressing
Before any data can be extracted from the database to tags, a user needs to understand the
database addressing sheme. In the same way that a PLC has its internal registers (a typical
integer register for AB can be N7:0, or for GE %R001) which store the actual data, the OI
database also has its own internal addressing. A new tab Database (Database_Read) is
created in the Tag Editor every time a new database read component is added to the
application. In this tab, a database address can be added and associated with a tag. The name
between the parenthesis matches the name of the corresponding database read component.
The format of the database addressing is as follows:
DB:order_of_record.name_of_the_column.
When the order_of_record is the offset from the current record;
Value 0 displays the current record.
Value 1 displays the record recorded previously to the current one, etc.
The name_of_the_column is the name of a column of the specified database table or
view. In database write component's term, it is one of the tags listed in the tagList property
and whose values was written to the database. In case the dataSource is not a table but a
result of a SQL query instead, the name_of_the_column should match the corresponding
name of the field returned by such SQL query. DataSource settings will be covered in later
sections.

Control and Status tags

In addition to the database tags, there are three important control and status tags, that allow
access to the data source from the OI terminal screen or from a PLC program:
Find Record is a control index, which points to a record in the specified data source. The
value indicates the number of records back from the newest record returned. It acts as a base
reference for the order_of_record. In another word, the record it points to corresponds
address DB:0.xxx. This tag allows us to page through records in the database source
since its value can be changed. If the Find Record index is out of range of the data source,
the currently selected record will be the closest one to the next valid number. To explain this
further, the selected record will always find the closest number within the limit. For example,
if a data source returns 100 records therefore with valid index range 1-100, and the Find
Record index is set at -1, the selected record will be 1.
Get Current Record indicates what record is actually being pointed to. For example, it may
occur that Find Record points to a non-existent record. The Get Current Record then
indicates the index of the valid record being displayed.
Get Total Records is the total number of records in the data source. This number becomes
constant when the tableRowsLimit in the table is reached, in which case, each new record
will cause the oldest record to be erased from the table, thus maintaining that the total
number of records is equal to the tableRowsLimit.

Examples
if the value of the FindRecord pointer equals 1:
DB:0.xxx references the newest record of the operator name.
DB:1.xxx references the record of the recorded before the newest.
if the value of the FindRecord pointer equals 2:
DB:0.xxx references the record of the recorded before the newest record.
DB:1.xxx references the record 3 steps before the newest record.
The rest of the DB:xx tags are offset in the same way:
If the value of FindRecord pointer is changed to 10:
DB:0.xxx references the record 10 steps before the newest record.
DB:1.xxx references the record 11 steps before the newest record.
DB:2.xxx references the record 12 steps before the newest record.
Note that the number of the record is counted from the newest record. This may be
confusing. If Find Record pointer equals 10, the displayed value comes from the first
(oldest) record recorded in a table with 10 records.

Setting Database Read Component Properties

Double click on the component to edit the component property:

 findRecordTag is a read tag used to control what record to select for actual display. See
control and status tag section earlier for details.

currentRecordTag is a write tag which reports the index of current valid record. See
control and status tag section earlier for details.

totalRecordsTag is a write tag which reports to the total number of records in the data
source. See control and status tag section earlier for details.

dataSource: Data source can be either a table, a view or a query. If we need to just read
data from one table/view only, we can fill in just the name of that table/view. The query can
read data from multiple tables and perform certain operations such as addition, minimum,
maximum etc. The query is written in PostgreSQL syntax. Check PostgreSQL documentation
(http://www.postgresql.org/) for details. Note that the SQL query should NOT be terminated
with ';'.
In addition to standard SQL query syntax, OI system also support tag substitution within
SQL query. The tag is marked by the '$' character. For example, assume we have a UInt tag
defined in the OI application as 'age_filter' and this tag can be manipulated via on screen
component such as a numerical input, or via PLC. Also, assume we have a database table
named 'employees' with some basic information. It is possible to enter the following as the
dataSource:
Select count(*) as subtotal From employees Where age > $age_filter
At runtime, the OI system would automatically substitute the value of the 'age_filter' tag
before running the query against the database system. Since there is only one record returned
by this query, the result in this case can be accessed by a database tag with address
'DB:0.subtotal'.

refreshTag: A change in the value of this tag will cause the data to be refreshed by re-

reading it from the database. This is similar to the trigger tag in the Database Write
component. This feature is needed when a data source other than the local OI is writing to

the database, or when values in older records are being modified. Same effect as
refreshTime but can be user triggered.

refreshOnEvent: ZeroToNonZero and AnyChange events are supported.

refreshTime: sets the time in seconds when the data is refreshed by re-reading from the
database. This is practical only in the case that another data source is writing to the same
database, or when values in database records are overwritten. It is not recommended to
enable this feature for computationally intensive queries or queries against large tables since
it may render OI system unresponsive while the query is in process. For this type of queries,
trigger based refreshTag should be used instead for on-demand update. To disable automatic
refresh, set refreshTime property to value 0.
Property refreshTag and refreshTime work independently and can both be used at the same
time.

5.11.3 Database Edit Component

The purpose of Database Edit component is displaying and editing values in the database
tables manually, without having to copy the values to a PLC or other devices. Database edit
component treats a database as a device in which an operator can access individual records
and fields from the OI touch screen. It acts and operates very similar to a Database Read
component with additional ability to write the values in the database tags to the table. This
component can work only with a physical table and can not work with a result of SQL
SELECT query. Direct access to the database frees the PLC resources and speeds up the
interface response.
An example of application is to record production data, which can be later edited and added
to manually, such as operator name or defect description.
A spreadsheet type table can be created on screen, displaying and allowing to edit data in the
database directly from OI. Such table can be built combining data entry and display
components, such as numeric or text input.
This component requires tags to be defined with database addresses just as in a database read
component. These tags can then be used for reading and writing to the database. The
difference is that the tags in Database Edit can be used for both reading and writing.

Setting Database Read Component Properties

Double click on the component to edit the component property:

findRecordTag is a read tag used to control what record to select for actual display. See control and
status tag section earlier under database read component for details.

currentRecordTag is a write tag which reports the index of current valid record. See control and status
tag section earlier under database read component for details.

 totalRecordsTag is a write tag which reports to the total number of records in the data source. See
control and status tag section earlier under database read component for details.

tableName: The table name identifies the table we need to edit.

refreshTag: A change in the value of this tag will cause the data to be refreshed by rereading it from the database. This is similar to the trigger tag in the Database Write
component. This feature is needed when a data source other than the local OI is writing to
the database, or when values in older records are being modified. Same effect as refreshTime
but can be user triggered.

refreshOnEvent: ZeroToNonZero and AnyChange events are supported.

refreshTime: sets the time in seconds when the data is refreshed by re-reading from the
database. This is practical only in the case that another data source is writing to the same
database, or when values in database records are overwritten. It is not recommended to
enable this feature for computationally intensive queries or queries against large tables since
it may render OI system unresponsive while the query is in process. For this type of queries,
trigger based refreshTag should be used instead for on-demand update. To disable automatic
refresh, set refreshTime property to value 0.
Property refreshTag and refreshTime work independently and can both be used at the same
time.

5.11.3 Database Table Component

The purpose of this component is to present contents of SQL database table, database view
or the result of a SQL query in a form of table. It does not require to define any tags for data
to display so it is not possible to manipulate those data using PLC. When any error occurs
during database connection or in data manipulation a label with error text is displayed at run
time.

For the purpose of this description we assume a table as:

1) physical SQL database table
2) view of a query which is defined by SQL language within the database system. In
case you want to update contents of the physical database tables you need to create
rules that rewrite inserts, etc. using SQL, see PostgreSQL documentation.
or
3) the result of a SQL query specified at dataSource within OI application.

Two component modes

1) read/write mode:
operates over table

allows browsing over records using horizontal and vertical scroll bars

allows editing individual field values when user clicks on particular field cell.
The column has to be set as read/write.
It is necessary to have an unique primary key index column in the
underlaying table for this function. If values in the index column are not
unique multiple rows will be updated.

allows inserting of new records when user clicks on left vertical header and
selects Insert from the pop up dialog.
It will call INSERT INTO table (indexColumn_name) VALUES (default). As
a result of this action an empty record with values defined in the table
definition will be inserted to the table. Then a user can edit individual fields of

inserted record.
The display position of inserted record in the table is according to orderBy
property. It also depends on default values defined in table. The new record is
not made visible automatically because its position is unknown.
In order to set the value of the index filed in the inserted record a function
(ex. sequence) must be defined in SQL database for this filed.

allows deleting existing records when user clicks on left vertical header and
selects Delete in the pop up dialog. As a result the selected record will be
deleted from the table.
This function uses index column of the table. If values in this column are
not unique multiple rows will be deleted.

allows filtering records in the table using filter property

allows sorting records in the table using orderBy property

Note: when this property is not set, the order of returned records is determined
by SQL database.

2) read only mode

it operates on SQL SELECT query

it only allows browsing contents of SQL query result using scrollbars

Setting Database Table Component Properties

readOnly: This property selects between read only or read/write component

operating mode. In the read only mode, properties which are not applicable are
disabled.

dataSource: this property defines name of a table in read/write mode or SQL

SELECT query in read only mode. In case the table with entered name does not
exist in SQL database or the entered SQL query is wrong an error label will be
displayed at runtime. The tag substitution syntax is supported as well just as in
database read component. Refer to earlier section for details. One exception, the
SQL query need to be terminated with ';' character.
Ex: If you simply want to display contents of whole table without editing, set
readOnly property to true and enter SQL query in a form SELECT * from
table_name;

indexColumn: the name of one index column of the table which is defined as
primary key. The value of a field in this column determines a record in the table. If
this column is displayed it is always read only it means values in this column
cannot be modified.

filter: a filter string is an SQL WHERE clause without the WHERE keyword. It
allows select only specified records from the table based on given condition.

orderBy: it affects the order in which data records are displayed. It is defined as a
list with each item having the form column_name order separated by ; (e.g., id
ASC;surname DESC)

refreshTag: (the same meaning as in DB Read component)

refreshOnEvent: (the same meaning as in DB Read component)

refreshTime:(the same meaning as in DB Read component)

numOfColumns: in case the value of this property is 0 the component will display
all columns as they are defined in the table or by SELECT query. Names of
displayed columns will be the same as names of table columns or SELECT query
columns. Each displayed column will have width 100 pixels. All columns except
index column will be editable.
If the value is nonzero it specifies number of displayed columns. The following set
of properties are available for each displayed column:

Column properties:
colHeading: specifies the heading of displayed column
dbColName: specifies the matching name of the column in table or SELECT
query
width: width of displayed column
readOnly: specifies if the user can edit contents of the column. If the column
is index column setting this property to false does not have any effect.