Home

Biostratigraphy
Geochronology

About StrataData

Staff & Associates

Contact

Blog

StrataBugs v2.1 System Administrators Guide

This guide is for the use of system support personnel tasked with installing and maintaining a StrataBugs v2.1 installation. The following skills are likely to be required:

Application platforms

Licensing

Licensing is controlled through the RLM product from Reprise Software. There are three licensing models that can be used:

The licence file may have any file name (and you can change the file name) but will always have a .lic file type. The file is plain text and can be examined with a text editor, but you cannot edit the file contents without risking making the file invalid (except for example, adding a port number for the licence server).

All types of licence file may be time-limited.

A full description of the licence file is available through the RLM site.

The licence file may contain a mixture of licence types.

Setting up the licence for a floating server:
Setting up a standalone licence:

Simply put the licence file into the StrataBugs v2 folder OR set the environment variable RLM_LICENSE to point to the location of the licence file. If the licence file contains a hostid which contains the text "SENTINEL=", then it will require a suitable matching dongle, with the Sentinel driver installed (see above). The dongle can be tested using the program spro.exe in the StrataBugs folder.

Diagnosing problems:

Run the application control panel with the following environment variable set: RLM_DIAGNOSTICS=rlmdiag.log, or start the application Stratabugs_diagnostic.exe, which will contain this setting. Messages are shown on the command line as well as to the log file.

Roaming licenses:

We may provide a floating licence which allows licences to be checked out for a period of time from the network server. If this is enabled you will have an argument to the LICENSE line in the licence file stating "max_roam=n" for the maximum number of days a licence can be roamed. To check out a licence, the environment variable RLM_ROAM should be set to the number of days the licence is required, before running the StrataBugs control panel. Thereafter the client can be disconnected from the network. A suitable script like this would work:

@echo off
REM start strataBugs with roaming options.
echo.
echo Enter the number days you want to take a StrataBugs licence for.
echo.
echo Enter 0 to leave unchanged.
echo Enter -1 to return the existing licence to the server.
echo.
SET /P RLM_ROAM=Days required :
echo.
echo. Remember to Open and Close the charts module

stratabugs
echo.
IF %RLM_ROAM% GTR 0 echo You can disconnect from the network and use StrataBugs for %RLM_ROAM% days.
SET /P TEMP=Press Return:

Additionally, if you have the flag "issuer=user_roam" set in the stratabugs LICENSE line of the licence file, you can enable users to choose roaming through the control panel themselves. The user selects the control panel menu option "Config | Licence roaming check in/check out". This brings up the following dialog:

The maximum number of allowable days roaming is set within the licence file, with an overall maximum of 180 days.

Application installation and startup

All the required files are contained within a single directory, with a sub-directory \lib. The system may be moved to another location by copying the contents of the folder and sub folder. Unlike v1.8 there are no registry settings which determine the location of the applications. Users need only to create a suitable shortcut to point to the executable (or jar file) in the deployment folder. The folder may therefore be a shared network drive or a local drive.

User installation:

The user installation process consists of running a Java application from the StrataData web site. Before this process can begin, system checks are made and, if necessary the Java Runtime Environment is installed prior. Thus, the JRE for application deployment is always present if the user installation is from the web site. The application SBUpdate.jar is the installer/updater application. This is the preferred method of installation because it:

An alternative method of installation would entail copying all the installation files, preserving the folder structure with the /lib folder. The latest production release is available for download here.

If you are downloading onto a different target, you can download all the files using the web site application, then copy the folder tree to the target machine. You may also need to install the JRE on the target machine if it does not already exist (see below).

The application can be launched with the launcher application StrataBugs.exe, or by using this command at the command line:

java -jar jsbugs2_1.jar

You may want to allocate more memory to the application on start-up, by adding this flag:

java -Xmx256m -jar jsbugs2_1.jar

You should see a "splash screen", then a licence check will be made. If a licence is not available for any reason, you will get the licence failure dialog. See above for licensing issues. If the licence check proceeds, you will get the Connect dialog, to make a connection to a database.

Note that the connection settings are stored per-user in user-allocated java backing stores. Each user must create their own connection settings, they cannot be shared.

All the StrataBugs v2.1 applications, with the exception of the legacy chart plotting application, are modules within the control panel application jsbugs2_1.jar. If required, the separate legacy chart application sbchart.exe is launched by the control panel. The .dll files in the v2 folder are loaded by the sbchart.exe application, and the supplementary libraries which support jsbugs2_1.jar are held in the /lib folder.There may be a /data folder which contains local databases, and by default includes the demo database.

Files with a file type of .old are backup copies that the updater application (from the web site launch button) has retained. If you need to go back to a previous version of the application, you can delete the file and rename the .old file. Note that the previous copies of .old files are overwritten by later updates. You do not need to keep the .old files for normal operation.

You can create a shortcut to StrataBugs.exe which will retain the correct application icon. The shortcut should be set so that the "Start in" folder is the v2 application folder.

Determining which version PROD or TEST to use

We maintain two distributions of the applications, both of which are available to the updater/installer application. We have a Test version and a Production version. The Production version is a stable, known configuration which we aim to refresh every quarter year, using a Test release that's stable. Contact us if you wish to be on the technical mailing list and be notified when a new production version is released. The production version will always be behind development of the Test version, which is the current latest build. Any new features or bug fixes will be added to the Test version. Generally, the production version will be less featured, and contain more bugs than the Test version, but it may have the advantage that it does not suffer from any unforeseen side effects of recent bug fixes or new features.

We recommend that you install the Test version, unless you have fixed update cycles and are unable to refresh your Test version as the need arises.

We frequently make changes and add new features that are requested by clients.

Offline installation of the JRE

You should go to java.sun.com and select the latest version of the JRE. Select the downloads tab, and look for the Windows x86 offline installation bundle. This will produce a runnable installation that can be copied to the target machine.

Database Administration

From the StrataBugs control panel, the menu option Help | Describe database will provide basic database statistics.

H2

This is currently the default platform for installations. The replaces the old Access format because it works with jdbc database drivers and across different operating systems. You do not need any H2 management application, unless you want to use it as a server (see below).The advantage of using H2 is that you can use Java 8 with jdbc drivers and in 64-bit mode. You can only use the legacy charts application with H2 by installing the PostGreSQL ODBC driver that works with this platform. H2 can be used in server mode or for a standalone database. The current version of H2 we use is 1.3.176. To set up H2 in server mode, refer to these instructions.

Access

This was the previous default database for standalone applications. You do not need a copy of the Access application (included in some editions of Microsoft Office) to use StrataBugs.

The Access database is usually called sbugs2-1.mdb. This file must reside in an area that has write permission to all database users. We recommend that you have a maximum number of 3 simultaneous Access users. If you have more we recommend using a server based database such as Oracle or SQL Server.

You can open the database using the Access application. The Relationships window provides a detailed view of the tables and their constraints.

The database must be periodically compressed to reclaim deleted space. You can use the Manage menu from within Access, or you can Compact and Repair the database from within the ODBC Administrator (on the edit data source dialog).

Warning: If you have your Access database on a network share we strongly recommend that you compact the database on the host machine rather than over the network, as network compaction can lead to file corruption.

You do not require a copy of the Access application to use StrataBugs with an Access database.

To make a backup of the database, simply copy the database file. As of version 2 StrataBugs, it is possible to store wireline logs and images within the database file and keep all the data together, however there is a file size limitation of 2Gb for Access files. If you are near this limit we recommend switching to an alternative platform, or unloading your images (there are menu options for this).

Oracle

Setting up the schema

The StrataBugs database under Oracle will consist of a collection of tables. You will be sent a table creation script (SBUGS-2_Oracle.sql), plus the update script for v2.1 and the demo data.. The steps to perform are:

Per user Login:

This is currently the most popular model, and was the only model supported by StrataBugs v1.8. Security to the table data is controlled by the Oracle DBA. Passwords are secure and an be expired if necessary. Each user is allocated a separate ORACLE user ID and password. When a connection is made to StrataBugs, the Oracle user ID is matched to an entry in the SYS_NAME field of the USERDEF table before proceeding as a recognised StrataBugs user. Thus, users connect on the Connection dialog with their database credentials, but as long as they are a registered StrataBugs user, and have privilege to read the schema tables, they connect without further interaction.

Adding a new user: The Oracle DBA creates a user and provides the user name. A minimal command to create a new user would be:

CREATE USER user IDENDIFIED BY pass DEFAULT TABLESPACE tbsp;

GRANT CONNECT TO user;

The StrataBugs control panel is opened by a Super user, and the menu option Config | Personnel is selected. The user is added, and their Oracle user ID entered in the appropriate field. The Oracle user is assigned a role, or given table privileges. Note that the Oracle user is not created using the StrataBugs application.

Adding a role: We recommend using a role such as SBUGS_USER in your Oracle database. This role can be assigned privileges on the schema tables, and users can be granted the role. The sql script SBUGS-2_Oracle_grant (supplied on request) can be used to assign the role to the tables. The role can then be granted simply using

GRANT SBUGS_USER TO user;

Single login:

As an alternative you can manage users entirely within the StrataBugs schema. In this instance you need only create the schema owner. All users are provided with the Oracle connection credentials for this user. It is important that under this model there is NO entry in Userdef.sys_name which matches the schema owner: all users are identified by separate StrataBugs users ID's and passwords which are encrypted in the Userdef table. To add a new user and manage users, the Config | Personnel option from the control panel is selected. You do not need to set any table privileges.

Database backup:

Your site policy should include backups for your Oracle databases. In addition you might need to regularly take a snapshot of the SBUGS2 schema. Use the "exp" Oracle utility to export all the tables to an Oracle .dmp file.

Microsoft SQL Server

From StrataBugs v2.0 onwards, we support the MSSQLServer platform.

Microsoft Access provides migration tools for 'upscaling' an Access database to SQLServer; it is easiest to use an Access database file (either the demo database or the result of database conversion) as the basis for a SQLServer database.

You will need to ensure that the ODBC drivers are available on the clients. You MUST use the SQL Server "Native Client" driver and not the plain "SQL Server" driver, otherwise you will get an error when you try to connect or use any of the modules. The error message states "Connection is busy with results from another command".

Similarly to the Oracle setup (above), we recommend creating a role which can be granted to all users.

There is a short guide to installing and using SQL Server Express.

MySQL

This platform is supported from v2 of StrataBugs. The database schema can be created in an similar way to Oracle, using a modified script available on request. The database software is available as a free-to-use edition or a supported edition. If you wish to forego the use of the (Windows) chart program (leaving the chart applications in Samples & Interpretations) you can run MySQL using pure JDBC (Java) drivers: this also allows the opportunity to run on non-Windows platforms (Linux, MacOS). Contact StrataData if this is of interest.

Migrating from a version 2.0 database

The migration process uses the SBConvert2_1.jar application. The process is documented for user conversions here on the Conversion page. Contact StrataData for more details.

Generating PDF output

If you get the error "Error while setting up fonts" while trying to output PDF files, make sure that the user has the permissions to write to a .fop folder from their home directory. This folder is required for setting up a font cache during the writing process.

 

Offline Chart Generator

This utility generates and updates charts of each well in the database. It is intended to be scheduled as a regular batch job, in order to maintain a folder of up-to-date chart images. It uses a template created within the main application (with a restriction that the template name must not contain spaces). The chart files are in PDF format, named with the relevant well code.

ChartGen requires no further file installation. To run from the command line, navigate to the StrataBugs folder and use:
java -Xmx1024m -cp jsbugs2_1.jar jsbugs.ChartGen

adding the following parameters:

Example: use the first two characters for a folder and the remaining for the file name. The path and url parameters could be path=D:\server.xyz\<W1:2>\charts\<W3:>.pdf url=http://www.xyz/<W1:2>/charts/<W3:>.pdf. If the well code was 500023234654, this would result in a file in D:\server.xyz\50\charts\0023234654.pdf and a url of http://www.xyz/50/charts/0023234654.pdf. You must ensure that the url maps correctly onto the file generated.

When you are satisfied with the parameter setup, you can create the windows batch file "ChartGen.bat." Example contents:

D:
cd "\sbugs\SBugs2\StrataBugs-2-1"
"C:\Program Files\Java\jre7\bin\java.exe" -Xmx1024m -cp jsbugs2_1.jar jsbugs.ChartGen driver=jdbc host=SRVR instance=SBUGS21 instancelogin=DBA password=system sbugslogin=SYS path="D:\sbugs\ChartGen" template=BiostratSummary > ChartGenLog.txt 2&>1

The final part of the file redirects the console output to a log file "ChartGenLog.txt". This file is replaced each time the process runs. It is useful for troubleshooting problems and also notes how many charts were generated or updated. Note that in 64-bit environments you must include the path to 32-bit java.

You can use the batch file to schedule a regular task. After their initial creation, charts will only be updated when relevant data have changed OR if the template has changed; new charts will be added for any new wells.