FairCom ODK Driver

Notes about the ODK Driver

FairCom Concepts

This section lists important terminology along with definitions and the implications this has on using the FairCom ODK driver.

Database

• The FairCom ODK driver can connect to only one database per PLC, which is the default database.
• A database contains zero or more tables.

Table

A table is two or more files stored in the operating system.

Each Table has a Table Name:

• The Table Name is a unique identifier for the table.
• Each Table Name must be unique in a database.

There are at least two files per table:

• Data file (*.dat)
• Index file (*.idx)

  The Index file makes it very fast to look up records by key.

  A table always has at least one index file to look up records for the Primary Key. For example, you could use a part record’s UID as the primary key.

A different table should be used for each different type of record:

• Each record in a table should contain exactly the same data structure.

  (FairCom does not enforce this rule, which means you can put any data structure in a record if it does not exceed the maximum size of the record. See the note below under Record)

• Examples:

  A part should be stored in a part table.

  A recipe should be stored in a recipe table.

  Parts and recipes should not be mixed in the same table.

Record

Each table contains zero or more records.

A table can contain millions of records.

Each record in a table should have the same data structure.

A record is variable-length:

• The length of a record is specified when it is inserted or updated. Records in the table can have different lengths.
• The driver uses variable-length records because they are more flexible. A variable-length record can always contain a fixed-length record, but the converse is not true.
• At any time, you can change the record length.

The FairCom driver does not limit or control the data stored in a record. Thus, it can be used to store any type of record.

Note: FairCom recommends storing the same data structure in each record of a table. When different data structures are stored in the records of a table, the FairCom database cannot provide advanced features, such as Structured Query Language (SQL) and automatic creation of JSON messages for delivery through MQTT.

Primary Key

Each record in a table must have a unique identifier called a Primary Key.

The Primary Key has a fixed-length (a fixed number of bytes).

The Primary Key is always indexed for fast and efficient record lookups. This index is called the Primary Key Index.

For example, you could use the UID as the Primary Key when storing parts in a table.

When doing record operations, the key is placed in one variable and the value in another.

IO Channel

All record operations (read, insert, update, and delete) occur on a dedicated IO Channel.

There are 32 IO channels.

• Each IO Channel has an integer number from 0 to 31.

Each channel may perform any record operation at the same time as record operations on other channels.

• Each channel processes data asynchronously to the other channels.
• This allows the database to take advantage of multiple CPU cores and to do multiple things when it is blocked by slower storage operations.

Retention Period

Retention Period puts a maximum limit on the growth of database files to help ensure storage capacity is never exceeded.

Retention Period is the maximum amount of time that a record remains in a table before the database automatically removes it.

• For example, when the retention period is 13 months, all records older than 13 months are automatically deleted on the first day of each new month.
• Deleted records cannot be recovered unless you configure the operating system to retain deleted files.

The default Retention Period is 13 months.

You can specify the period as units and a measure, such as 13 months where "13" is the number of units and "months" is the measure. The possible units are Year, Month, Day, Hour, and Minute.

A Retention Period has a natural cycle based on when its internal unit of measure resets.

For example, a month cycles on the first day of a month. A day cycles on the first hour of the day (i.e. midnight).

A Retention Period creates buckets of records inside a table.

• For example, a Retention Period of 13 months creates 13 monthly buckets of records.

When a Retention Period cycles, all records in the previous period are automatically and immediately deleted.

• A Retention Period deletes outdated buckets of records (not individual records)
• Each time a month cycles, the oldest bucket of records is deleted.

For best performance, choose a Retention Period that cycles before accumulated records in each period become excessive.

• For example, on slower hardware a bucket containing 100,000 records may be excessive. Thus, choose a Retention Period that cycles buckets before they contain 100,000 records.

Data Replication

Data Replication allows data in specific tables on a Primary IPC to be replicated to one or more secondary IPCs.

Data can be replicated in two ways:

• Synchronous Replication

  PRO: No data loss

  It guarantees all data changes occur on two IPCs.

  CON: up to 50% slower data changes

  Because it requires the database to write to two computers at the same time, it has the potential to slow down inserts, updates, and deletes by 50%.

• Asynchronous Replication

  PRO: No performance loss - A primary IPC can replicate its data to many other IPCs with no significant impact on performance.

  CON: Potential data loss - It guarantees all data changes occur on two or more IPCs within a few seconds. If the primary IPC fails before the data is replicated, the secondary IPCs will be missing the data changes.

Standard Siemens States for Function Blocks

• Done
• Busy
• Status code
• Error

Busy, Done, and Commits

FairCom Edge uses an ACID-compliant, transactional database that implements the concept of a commit.

• A commit is the idea that data is not persisted to disk until the database has reported back that it has been committed. And once the database reports the data is committed, it is guaranteed to be on disk.

The Driver uses the Busy and Done status flags to report the status of an operation.

• Busy

  When Busy is true, it indicates that the operation is in progress.

  If the operation is doing an insert, update, or delete, it indicates that the data is also not yet committed.

• Done

  When Done is true, it indicates that the operation is complete.

  If Error is false, then the operation completed successfully.

  • If the operation did an insert, update, or delete, it indicates that the data is committed.

  If Error is true, then the operation failed.

  • If the operation did an insert, update, or delete, it indicates that the data is not committed.

Error Handling

The FairCom ODK driver and FairCom Edge reports error messages in text as well as the error message codes. The driver uses Siemens ODK Fileserver error numbers as applicable. The error codes are not limited to the Siemens ODK Fileserver error codes. FairCom has provided additional codes where appropriate.

General Error Handling Principles:

• When an error occurs, it sets the Error State and Error Number.

  An Error State is set when:

  • Any parameter has an invalid value.
  • Expected error occurs.
  • Unexpected error occurs.

  When a parameter has an invalid value, it is a programming error that must be fixed.

  • Invalid value errors are defined in this documentation for each type of parameter.
  • They are specified in the first definition of the parameter.

  When an expected error occurs, the action depends on the application’s needs.
  Expected errors are documented in each function.

  • When an unexpected error occurs, it is a system issue that prevents the driver from proceeding, such as no available disk space or an unexpected FairCom bug.
    System errors are documented on FairCom’s website.