Creation and Configuration of Databases

The creation of databases and the configuration of remote databases is a part of the general PMOD configuration. It is opened by calling the

button from the PMOD ToolBox, and selecting the DATABASE tab in the appearing dialog window.

To create a new database please proceed as follows.

Derby JDBC Database Creation (default)

1. Create a new entry in the database list using Duplicate data source or Add new data source:
   
   A dialog window is shown for requesting a name for the new database. The new data source is added to the list selection and must be configured in the lower section. With Duplicate the same settings as for the selected database are applied, otherwise the default settings. Note: Please do not change the data source name after the database has been in use.

   Create a new entry in the database list using Add new data source from existing folder. With this selection it is mandatory to provide the same name of the data source to the new database. Define the configuration in the Select database folder window pointing inside the data source folder such that the db.lck is visible in the in the Files area. Activate the Echo DB button to verify the proper connection. Note: Do NOT use the Create Database button with this option.

2. Use Direct Connection: Only JDBC databases can be created, so this radio button must be selected.
3. Database Connection: This entry defines the database access. The first part jdbc:derby: is the driver specification. The Database Name is the name by which the data source is known to the database engine. In principle the name can differ from the data source name, but this is not recommended.
4. Database Path: The directory where the database tables are stored (in a subdirectory named corresponding to the database name). It is highly recommended to replace the default path by an absolute path pointing to a central location outside the PMOD installation. This will make it easier to perform version upgrades as well as backups. If relative path names are used starting with "./", the directory will be placed in Pmod3.9/data.
5. File Storage Area Path: This is the path of the root directory in which the data files will be stored. As for the DATABASE Path it is recommended using an absolute path, preferably in a common directory.
6. Create Data Base: Activating this button finally creates the JDBC database. Connectivity can be tested with the ECHO DB button.

Note: After the installation of Pmod3.9, the Pmod database illustrated above is already available and contains different types of example data, if the example database was selected for installation.

mySQL JDBC Database Creation (deprecated)

The only difference to the procedure for the Derby database is in step 3, Database Connection. Please configure as follows:

The first part is the driver jdbc:mysql. The second part is the host on which the mySQL server is running, in the example above the same machine PMOD is running on, thus localhost. The third part is the mySQL database name, Pmod. In principle the database name can differ from the data source name, but this is not recommended.

User:Password: Fields to specify a user who has administrator privileges in the addressed mySQL installation and his password. The standard setting of mySQl is root and an empty password. If mySQL requires to enter a non-empty password for root, please specify it in this password field.

Note: You can create different SQL databases to collect data for different projects. They must, of course, have different names and should most likely save the data files in different directories.

Configuring Transaction Server Databases

PMOD allows publishing a local data base to other PMOD installations by a server program called Transaction Server. To address a remote transaction server database, a data source must be defined as follows:

1. Add new data source: Again, a new data source must be created and adequately named.
2. Use Transaction Server: This radio button must be selected, and the transaction server address and port entered.
   
   In this example, PMOD is installed on a host called localhost where a transaction server for a particular JDBC database has been started listening on port 5100. As the database is already existing, the initialization step is not necessary.
3. Note the Secure box. Please configure the communication with the properties that the transaction server is expecting (see below).
4. If the transaction server is running, connectivity can be tested with the ECHO button.

Numerical Accuracy of Images Stored in the Database

Images are stored to the database using Enhanced DICOM IODs which are selected according to the image modality setting. The accuracy of the standard IODs is limited, and if the images have a large dynamic range rounding errors can occur. In these situations PMOD may use a private IOD which supports floating numbers to avoid rounding errors. This behavior is enabled by the Database supports FLOAT representation of image objects box.

The float representation is an advantage if the images are used for further processing in PMOD. However, when such images are exported, PMOD converts the images to the standard IODs, whereby the rounding errors might be introduced.

Multiple Access to Derby JDBC Database

It is the nature of embedded databases such a Derby that they can only be accessed by a single process. Therefore, if you start two instances of PMOD, only the first one will be able to access the database directly. The second one will not get access and show an error message

The solution for this case is to publish the database by a transaction server and access the data through it. In this way, an arbitrary number of processes can access the database.

Note: The default configuration of Pmod3.9 already includes a transaction server definition of the Pmod database which is called DbSvr. The transaction server will be automatically started with the first interactive PMOD session. Access to Pmod through the transaction server is configured as the DbSvr database.

Database Deactivation

Sometimes there is a need to temporarily deactivate a data source, e.g. because a remote system is down. In this case the box Inactive can be checked to avoid lengthy timeouts.

Default Database

The database which is shown in the data source list when the configuration is saved will serve as the database initially. However, once in use PMOD remembers the least recently used database.

Database Upgrading

After updating a PMOD installation there might be a need to adjust the data structure of the existing databases for using them further. To do so, select a JDBC data source and activate the Update & Optimize button. This operation will not only update the table structure, but also the indexes and may dramatically speed up the access to aged, large databases.
Note: Transaction server data sources must be upgraded on the site of installation.

Database Backup

It is important to regularly back up the directory of the database tables as well as the data directory. This has to be done externally by the computer system administrator using reliable mechanisms for backing up important data.