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 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 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 propertyNote: 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.