How-to Guides

This section of the Polyhedra developer web site concentrates on showing how Polyhedra features can be used to achieve certain effects. Some of the articles are short, showing a simple tip or trick; others are more lengthy, and go into detail of how several features can be combined to provide significant new functionality. Articles in the latter category may have an attached PDF version for ease of printing and off-line reading. In some cases, a copy of the code or configuration files is included in the Polyhedra releases kits, in a subdirectory of the 'examples' directory.

The table below lists all the articles in this section, in alphabetical order. Following that is a cross-reference section, showing which articles discuss or make use of a particular Polyhedra feature (including articles in other sections of this website).

The Guides

Access Control

reference manual section 9 of the RTRDB reference manual
how-to
Adding audit trails to a Polyhedra IMDB database shows how the user-based security mechanisms built into Polyhedra can be adapted via CL code attached to the database into a role-based system. (The historian is used to capture and store the audit trail.)

Active Queries

white paper Active Queries
webcast The three-part demo of active queries (covering why, what and how) specifically addresses this topic, but many of the other webcasts on this site also show active queries in action!
demos in the release kits demo_1, documented in section 2.5 of the Evaluation Guide. This covers three applications, active, animate and websocket, that use active queries and that are provided in both source code form (the first two in subdirectories of poly8.6/examples/clients, and the other in poly8.6/examples/websocket) and executable form in the release kits. In fact, the directory poly8.6/examples/clients/active contains examples of how the client application can be coded using a variety of the Polyhedra APIs, and the poly8.6/examples/clients/animator directory shows how client applications can update the database 'through' an active query, using both the Polyhedra Callback API and also the ODBC API.
 
demo_4, covered in section 2.8 of the Evaluation Guide, builds on demo_1, and shows the client applications with connections to two database servers acting as a fault-tolerant pair. demo_4 is the basis for the '5-minute demo on Polyhedra' webcast.

demo_linx_active contains a version of the standard active example that has been adapted to use the SQLHandleLINXSignal function, which allows easier integration with applications that are making heavy use of Enea's LINX transport protocol.

demo_ado.net contains a C# program (and a Visual studio 'solution file' that can be used to build it) that launches an active query via the ADO.NET data provider for Polyhedra. There is a webcast showing both the client being built and also it being run. 
how-to The polygpio client described in Controlling the GPIO lines of a Raspberry Pi uses two active queries.

Callback API

(see Client APIs)

CL

white paper CL database triggers
reference manual CL reference manual
Various built-in classes that can be used by the CL programmer can be found in the CL communication classes manual, the CL schema classes manual and the Utility classes manual.
demos in the release kits demo_4, covered in section 2.8 of the Evaluation Guide, uses a CL coded application (for use with the CLC executable) that emulates 'arbitration agents' that would determine which of a fault-tolerant pair of servers should be master, and which should be the hot standby. (It is NOT a good starting point for developing your own arbitration code, as it acts as a single point of failure; it is provided simply to help run the demo - see the section on fault tolerance, below.) The CL code makes use of the tcpserver and tcpconnection classes (documented in the CL communication classes manual) to allow the database servers to connect to it for control.
 
demo_5, documented in section 2.9 of the Evaluation Guide
 
demo_db_arb uses CL in an 'arbitration database' to control fail-over for a fault-tolerant pair of database servers
 
demo_db_db_queries uses CL attached to one database to show how it can connect to and monitor a table in another database via an active query.
 
demo_globalfn provides a useful collection of CL-coded 'global functions' that may be of use to you.
 
demo_runner provides a sample CL-coded application (powered by the CLC executable) that can start up and monitor a Polyhedra database. This makes use of the program class (not available to CL running in the RTRDB); this is documented in the utility classes manual.
 
demo_shrink_db uses CL attached to the journalcontrol table to generate a new snapshot whenever the database file gets too large because of attached journal record. (This demo is only applicable to the IMDB editions of Polyhedra; Polyhedra Flash DBMS uses shadow paging rather than journal logging to achieve transaction durability.)
 
demo_singleton illustrates global functions, and initialisation of global functions as well as trigger code attached to a database; see the 'how-to' guide Managing and using single-record tables for a description of this demo.
how-to Adding audit trails to a Polyhedra IMDB database
Auto-incrementing fields  
Managing and using single-record tables
CL crib sheet
CL reserved words
Controlling the GPIO lines of a Raspberry Pi
Inspecting the schema of a Polyhedra database has an attachment which contains a CL-coded client application.

Client APIs

Reference manuals Callback and Socket APIs
Polyhedra JDBC reference manual
Polyhedra ODBC reference manual
ADO.NET data provider for Polyhedra
webcast
There is a video on installing and using the ADO.NET data provider for Polyhedra, which shows a C# program being compiled and run. The source code for the example is in the demo_ado.net directory in the Polyhedra release kits. frame from the webcast on the ADO.NET data provider for Polyhedra
demos in the release kits examples/clients contains the source code for a number of example applications. Some of these are also supplied in executable form (using the ODBC-coded version of the example), and their use is documented in section 2.5 of the Evaluation Guide. This covers three applications, active, animate and websocket, that use active queries and that are provided in both source code form (the first two in subdirectories of examples/clients, and the other in examples/websocket) and executable form in the release kits. In fact, the directory examples/clients/active contains examples of how the client application can be coded using a variety of the Polyhedra APIs, and the examples/clients/animator directory shows how client applications can update the database 'through' an active query, using both the Polyhedra Callback API and also the ODBC API. The animate and active examples are shown in action in the 5-minute Polyhedra demo.

poly<x>.<y>/examples/demo_ado.net) contains the C# source code for a client that launches an active query through the ADO.NET data provider for Polyhedra, and there is a webcast of it in action (see above). (The animate client has a supporting role in this webcast, as does SQLC.)
how-to Connecting to a Polyhedra server describes the various APIs, as well as giving some example code; it also illustrates how the Polyhedra ODBC and JDBC drivers can be used to access Polyhedra from PHP, Python, .NET programs and third-party applications.

Fault Tolerance

white paper High Availability
webcastsAs fault-tolerance is a key feature of Polyhedra IMDB and Polyhedra Flash DBMS, it is shown in action in a number of webcasts, including the 5-minute demo of Polyhedra and Polyhedra for SCADA and IoT. Webcasts specifically on this topic are a two-board demo of fault-tolerance and Polyhedra under the control of Element.
reference manual section 13 of the RTRDB reference manual
demos in the release kits demo_4, documented in section 2.8 of the Evaluation Guide. This is shown in action in the 5-minute Polyhedra demo webcast. It uses a TCP-based arbitration protocol to tell each server whether it should be master or standby, with the arbitration handled by a CL-coded application. This simple arbitrator is supplied simply for use in the demo as it would act as a single point of failure if used in a real FT system - so there is some C code that can be adapted to hook in to a customer-supplied mechanism for deciding which of two boards is master. (It is NOT a good starting point for developing your own arbitration code, as it acts as a single point of failure; it is provided simply to help run the demo. The file sample.c in the demo directory is the proper starting point for writing your own arbitrator, or the CL-coded arbitrator that accompanies the webcast on a two-board fault-tolerant configuration of Polyhedra. The TCP-based protocol used for the controlling the FT mode of a database server is described in an appendix to the PDF version of the Evaluation Guide.)
 
demo_db_arb shows how one can configure a third Polyhedra database server to act as an arbitrator, controlling a pair of database servers to offer a fault-tolerant database service. This can be used in a live system, but it does rely on having three machines and a reliable network.

demo_linx_arb contains C code that uses messages over Enea's LINX transport protocol to instruct a server whether it should be master or standby. It would need to be adapted to hook in to a customer-supplied mechanism for determining whether a board was in master or standby mode.

Historian

white paper Handling time-series data
webcast
Polyhedra for SCADA and IoT shows trend diagrams being fed with data captured by the historian. There is a separate how-to note describing how the historian was configured - see below. a trend diagram, taken from a frame of the webcast
reference manual The Polyhedra Historian module
demos in the release kits demo_historian shows a simple example of configuring the historian
 
demo_historian_xml contains the source code for an example application that uses the ConvertToXML() function to convert a historian archive file to an XML format
 
streamclient contains the source code for an example application that uses the Historian's "streaming output" API (introduced in Polyhedra 8.3) to monitor the samples generated by the historian in close to real-time.
how-to Adding audit trails to a Polyhedra IMDB database uses the historian to record when connections occur, and when people log in to the database server.
Combining subscription (partial replication) and the Polyhedra historian shows one way of setting up the historian both in a remote database and in a central database that subscribes to the remote, so that trend diagrams see the same information regardless of which server they query. This can be seen in action in this webcast.

JDBC

(see Client APIs)

.NET

(see Client APIs)

ODBC

(see Client APIs)

PHP

(see how-to document listed under Client APIs)

Python

(see how-to document listed under Client APIs)

Replica servers

white paper read-only replicas
reference manual section 14 of the RTRDB reference manual
demos in the release kits demo_replica, shows how one can configure a third and fourth Polyhedra database server to act as replicas of a pair of database servers that are in a fault-tolerant database configuration.
how-to Setting up a read-only replica server

Security

(see access control)

SQL

white paper Table Inheritance discusses a Polyhedra-specific extension to SQL, the ability to define one table as derived from another.
Most of the other white papers contain SQL snippets which may help illustrate how Polyhedra SQL can be used.
webcast There is no webcast concentrating on Polyhedra SQL, but all of them show SQL in action, being used via the SQLC client application. The 5-minute demo is probably the best place to start.
reference manual The Polyhedra SQL Reference manual
(Note: the SQLC reference manual describes the SQLC command-line client for Polyhedra. This defines some additional syntax which is understood by this client application, not the SQL engine inside the rtrdb, the Polyhedra database server. It is important to recognise that SQLC commands such as include, quit, commit and rollback are not part of Polyhedra SQL, and that it is SQLC that handles the -- and /*...*/ comments, which are stripped out before passing the SQL to the database server.)
demos in the release kits Almost all the demos in the release kits contain .sql files (the exceptions being those that simply demonstrating how to configure replication or control fault-tolerance, or those that are illustrating CL feature that are not specific to the database). In the demos, any file called tables.sql contains SQL to set up the schema for the demo, while data.sql files populate the database. In the case of demo_1 to demo_5, the .sql files to recreate the database from scratch are in the init subdirectory.
how-to All of them use SQL, and some of them use the Polyhedra SQL extensions.
A list of the reserved words in Polyhedra SQL can be found in the reference manual and in one of the crib sheets.
Inspecting the schema of a Polyhedra database describes the schema inspection tables, mentions some third-party tools, and has (as an attachment) a CL-coded application that can be used to produce SQL that will regenerate the schema for a database

Subscriptions

white paper DB-DB subscriptions for live caches
webcast Database subscription in action
reference manual Section 15 of the RTRDB reference manual describes the subscription mechanism, and the Utility Classes manual gives details of the tables used to set up and control the subscriptions made by a database on other database(s).
demos in the release kits demo_subscription contains some sample databases using subscriptions, plus running instructions
how-to Combining subscription (partial replication) and the historian gives some details behind the Database subscription in action webcast, including code snippets.