SIRA_PRISE Manual installation procedure

Let’s take a look at what is needed to get you going with this new system. There are several archive files in your downloaded package.  The following table lists the files that are needed for the various functions of the package :

Running the SIRA_PRISE server sp.server.jar
Addressing the SIRA_PRISE server from a java program sp.client.jar
Using the webclient to administer SIRA_PRISE databases SIRA_PRISE.war
Using the birdwatcher demo application birdwatcher.war, birdwatcher.zip
Using the standalone database browser sp.dbrowser.zip
Running the testset sp.testset.zip

Prerequisites

A Java™ VM, version 1.6.0 or later, must be accessible on the machine where any of the SIRA_PRISE components are to be installed/run.

In order to be able to install and use the SIRA_PRISE web client, a Web application server (e.g. Tomcat, Jetty, JBOSS, WebSphere, GlassFish, ...), must additionally be installed, operational and accessible on the machine where the webclient is to run.

Installing the server

Choose or create a directory where the program files will be installed (e.g. C:\program files\SIRA_PRISE or /bin/SIRA_PRISE). Extract all the files named sp.*.bat to that directory, and also the jar file needed to run the server (sp.server.jar). Users of the unix family of OS know undoubtedly that the bat files are of no use to them, unless they're translated to some "higher" shell/scripting language. Doing that shouldn't prove too difficult, because with the exception of the sp.sysgen.bat procedure, the .bat files contain only one command issuing the needed java/javaw invocation.  Then from the SIRA_PRISE installation directory, run one of the two provided sp.sysgen.bat procedures and answer all questions asked to the best of your ability.  The sp.sysgen.CL.bat is the old command-prompt installation procedure, the sp.sysgen.SwingUI.bat is the new, Swing-based, GUI procedure.  Either will do.

Concerning the catalog page size, something in the range from 16K to 32K is probably most appropriate. The remainder of the questions just concern quantity estimates allowing the installation procedure to determine the needed initial physical size of the catalog.

To give you an idea of the resulting initial catalog size, and just as a possible guideline, here are some values that should suffice to get you going, and the resulting catalog file size :

# of dbms files : 150
# of distinct data spaces : 750
# of relvars : 4000
# of virtual relvars : 10000
# of attributes : 16000
# of attributes per relvar : 6
# of keys per relvar : 2
# of attributes per key : 2
# of records per relvar : 1.5
% of attributes present in one record : 80
# of indexes per record : 3.5
# of java-implemented data types : 50
# of user-defined data types : 100
# of constrained types per type : 15
# of possreps per type : 1.5
# of components per possrep : 1.5
# of databaseconstraints per relvar : 8
# of relvars per databaseconstraint : 3
# of transaction and/or assignment constraints per relvar : 8
# of triggered data actions per relvar : 8
# of certified clients using the server : 100
# of certified users using the database : 5000

This gives a catalog of roughly 560M initial size.

The installation procedure will end with the message : "System Generation completed successfully.". A file named DATABASECATALOG.SPDB has appeared in the DATABASES subdirectory of your chosen SIRA_PRISE data directory. You are now ready to start the server.

(If something goes wrong, a SYSTEM.ERR file and a SERVERENGINE.LOG file will have been created in the LOGS subdirectory of your chosen SIRA_PRISE data directory, both containing more info about the precise nature of the problem. But we do hope you’ll get to see none of that.)

Installing the web client

Most modern web application servers have an autodeploy feature which makes it very easy to install a new web application.  Usually, the only thing that needs be done is to copy the WAR file containing the application to the autodeploy directory of the web application server.  E.g. on a GlassFish server installed on Windows, this is a directory typically called "C:\Program Files\Sun\AppServer\domains\domain1\autodeploy".  With a Tomcat server, this is simply the 'webapps' directory in the Tomcat installation.  For more details or for your particular application server, please consult the documentation that came with your web application server on how to use its autodeploy feature.

For installing the web client, the only step needed is thus to follow your application server's autodeploy procedure using the SIRA_PRISE.war file included in the package.

Installing the birdwatcher demo application

Installing the birdwatcher demo application involves two steps : installing the birdwatcher webclient and setting up the database.

Installing the birdwatcher web client is done using exactly the same procedure as when installing the database administration web client, only this time you should place the birdwatcher.war file in the autodeploy directory of your web application server.

Setting up the database is done by running the scripts that are included in the birdwatcher.zip file.  This requires that the server is running, and the java client libraries have been installed.  For more information on running scripts, please see the page on that subject.

Installing the java client

The java client is a library that you can use in your java programs to make those programs interact with a SIRA_PRISE server.  Place a copy of the sp.client.jar file in the library path of your application, just as you would include any other library in them.

Installing the standalone database browser

The standalone database browser is a self-contained, Swing-based, GUI interface to a SIRA_PRISE server.  Install it by simply unzipping the contents of the sp.dbrowser.zip file to a directory of your choice.

Advanced server setup

Different values can be chosen for most of the options used in the installation procedure. To do this, a configuration file must be placed in one of the following locations (in the engine's search order) :

  1. the engine's classpath.
  2. the engine's current working directory (i.e. the value of the user.dir property in the server's JVM)
  3. the engine's home directory (i.e. the value of the user.home property in the server's JVM)

The name of this configuration file is 'be.SIRAPRISE.server.ServerEngine.properties' (note that if the the configuration file is put inside a jar file in the classpath, it can also be named 'be/SIRAPRISE/server/ServerEngine/properties', in line with the usual conventions for naming of resources that are loaded through a ClassLoader). Following entries can be put in this file :

Property Description
CATALOG=ccc specifies that the file name of the catalog file is ccc. This option exists only for backward compatibility with engines generated by versions prior to 1.2. If this option is absent, it should not be introduced, and if it is present, it should not be changed.
DBMSFILEDIRECTORY=fff specifies that the directory name for the database files is fff.
DBMSLOGSDIRECTORY=lll specifies that the directory name for the database log files is lll.
DBMSJOURNALSDIRECTORY=jjj specifies that the directory name for the database journal files is jjj.
DBMSRESOURCESDIRECTORY=rrr specifies that the directory name for the engine's general-purpose resource files is rrr.
FORCEMETADATAWITHCONTENT=true|false defines whether or not, when forcing out data to the disk during a commit, the disk file's metadata are to be forced out as well.
SOCKETACCEPTTIMEOUT=msmsms specifies the number of milliseconds that the server will wait for an incoming connection before it times out and exits. Keeping the server running forever by specifying zero is not supported. Specifying "forever" must be approximated by using the highest possible value, which is 2147483647 milliseconds, or almost 25 days. Note that if you effectively run the server for this period of time, you won't be taking backups during this period either, which is not exactly the brightest of ideas.
GAPCOMPRESSIONRUNTIMEINTERVAL=msmsms The time in milliseconds between executions of the TimerTask that performs gap compression on physical database pages. The default is 60000. The value cannot be set lower than 1000. Database pages are added to the input queue of this automatic dbms task if the number of gaps that have appeared on the page exceeds the compression threshold value of the storage space the page appears in. Gaps can appear on a page as a consequence of some information being deleted from it by some user task. The addition of a page to the input queue of the compression task happens when the user task commits. Thus, the page compression doesn't slow down the user task causing it.
PAGEPOOLCLEANUPRUNTIMEINTERVAL=msmsms The time in milleseconds between executions of the TimerTask that cleans up the page cache. The default is 60000. The value cannot be set lower than 1000. This task removes pages from the page cache if they have been unused for more than the time specified in the KEEPPAGEINPOOLMILLIS option.
KEEPPAGEINPOOLMILLIS=msmsms The time in milliseconds that a page can reside in the page cache without being accessed, before it becomes eligible for removal from the cache. The default is 30000. The value cannot be set lower than 1.
PAGEPOOLGCTHRESHOLD=nnn The threshold at which page cache cleanup also becomes possible within the user transaction (i.e. consuming extra actual processing time within the user's transaction). If a user transaction makes the page cache contain a number of pages exceeding the value specified for this option, then page cache cleanup is executed immediately within (and thus at the expense of) the transaction. The default value is 5000. Cannot be set lower than 1.
CONNECTIONPOOLCLEANUPRUNTIMEINTERVAL=msmsms The time in milleseconds between executions of the dbms's automatic task that performs cleanup of idle connections. The default is 300000, and the value cannot be lower than 1000.
RESOURCEPOOLCLEANUPRUNTIMEINTERVAL=msmsms The time in milliseconds between executions of the dbms's automatic task that performs cleanup of the resource pool. The default is 60000, and the value cannot be lower than 1000.
LOCKDENIALWAITTIME=msmsms The time in milliseconds that a transaction thread will wait before retrying, when it has been denied access to a page or resource due to some lock held by another transaction. The default value is 250, and cannot be set to a lower value than the virtual machine's "time granule". The virtual machine's "time granule" is, approximately, the unit value by which the System.currentTimeMillis() value changes between two consecutive invocations of that method that produce distinct results. In some popular java implementations, this value is approximately 50, presumably owing to the 18 ticks-per-second clock from the old DOS days that apparently still persists to day.
LOCKDENIALRETRYCOUNT=nnn The number of times that a transaction will attempt retrying to access a resource if it has been denied access to that resource due to a lock on that resource held by another transaction. The default value is 5, and cannot be lower than 1.
CONNECTIONIDLETIMEMAX=msmsms The maximum time in milliseconds that the server will allow connections to remain idle. The idle time for a connection is requested by the client making the connection, but that requested value is "topped off" by SIRA_PRISE to the value of this option. The default value for this option is 120000, and cannot be lower than 1024.
SIGNATUREALGORITHMS=x,y,z Defines which Signature algorithms are supported by the server engine.