StrataBugs v2.0 System Administrators Guide
This guide is for the use of system support personnel tasked with installing and maintaining a StrataBugs v2.0 installation. The following skills are likely to be required:
- Thorough understanding of the application deployment infrastructure within your organisation
- A knowledge of file system management, security and backup
- An understanding of system services
- An understanding of the chosen database platform(s)
Application platforms
- Java Runtime Environment v1.6 or 1.7, 32-bit.
- ODBC database driver (32-bit) for the target database
- Microsoft Windows which supports the above JRE. (i.e. XP, Vista, Windows 7, Windows 8)
Licensing
Licensing is controlled through the RLM product from Reprise Software. There are three licensing models that can be used:
- A license server process (rlm.exe) running on a designated license server machine, serving floating network, per-use licenses. This is the default model for corporate networks.
- A hardware key (dongle) manufactured by SafeNet Serial no. 05470, which attaches to the USB port of the client, through the installed driver. This is the default model for single user licenses. The software may be run on any machine which contains the licence file and has the dongle attached. The driver does not need to be installed if you are running a floating licence server (as above).
- A licence file encoded for the client machine. This is the default model for evaluation systems. The licence will only run on the target client.
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:
- Download the RLM end user bundle from the RLM site.
- Run the utility "rlmutil.exe rlmhostid". Report the hostid of your server to StrataData support.
- When you receive the license file, download the ISV daemon package from StrataData support with: http://support.stratadata.co.uk/RLMstratadata_set.zip
- Follow the RLM instructions to start the rlm service with the license file, with a command like rlm -c<licence file>. You should see startup messages about the server starting.
- Install the licence server as a service (see RLM instructions).
- If you receive an error message about preventing running the license server on a virtual machine, we can supply a licence file which will permit this on request.
- Provide a reference for the clients using port-number@license-server-host as an environment variable assigned to RLM_LICENSE:
- For users, go to the Windows Control Panel | System | Advanced system Settings | environment Variables, and add a User or System variable.
- The variable name is RLM_LICENSE and the value might be 5053@server-host
- The server has a built-in web server which allows easy monitoring and administration, simply point a browser to "server-host:5054" to connect to the process, where server-host if the name of your 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:
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:
- Only installs or updates files that are newer.
- Will be updated to include new files as necessary if they are added to the distribution.
- Enforces installation of the JRE.
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_0.jar
You may want to allocate more memory to the application on start-up, by adding this flag:
java -Xmx256m -jar jsbugs2_0.jar
See these instructions for setting up a shorcut to StrataBugs on the desktop.
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.0 applications, with the exception of the multi-well chart plotting application, are modules within the control panel application jsbugs2_0.jar. The separate 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_0.jar are held in the /lib folder. As of February 2012 the folder contents are:
Main folder:
chart.zhp
cw3230mt.dll
jsbugs2_0.jar
jsbugs_help.zip
rlm902.dll
rlmjava803.dll
rlmsbchart.exe
sbchart.exe
SBconvert2_0.jar
sbugs.zhp
sbugs2-0.mdb
sbugs2-0_demo.mdb
SBugsML2-0.xsd
sp32w.dll
spro.exe
StrataBugs.exe
StrataBugs_Diagnostic.exe
sx32w.dll
tls704d.dll
v2Lithology.dat
zap4d.dll
zhelp.exe
zip4d.dll
/lib:
Model2.jar
fop.jar
Model1_8.jar
util.jar
swing-layout-1.0.3.jar
poi-3.8-20120326.jar
dom4j-1.6.1.jar
poi-ooxml-3.8-20120326.jar
poi-ooxml-schemas-3.8-20120326.jar
xmlbeans-2.3.0.jar
serializer.jar
resolver.jar
jdom.jar
rlm902.jar
xercesImpl.jar
avalon-framework-4.2.0.jar
batik-all-1.7.jar
commons-io-1.3.1.jar
commons-logging-1.0.4.jar
xml-apis-ext-1.3.04.jar
xmlgraphics-commons-1.5.jar
jai_codec-1.1.3.jar
jai_core-1.1.3.jar
jai_imageio-1.1.jar
StrataBugs.ico
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.
Access
This is currently the default platform for installations. 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-0.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 96 tables. You will be sent a table creation script (SBUGS-2_Oracle.sql). The steps to perform are:
- Create your schema owner. We suggest using the name SBUGSDBA or SBUGS2. The schema owner does not require Oracle DBA privileges, but must have CONNECT, CREATE SESSION and RESOURCE privilege and enough tablespace to accommodate the database.
- Connect to Oracle. You can do this via SQL*Plus, SQL Developer or a third party product such as Toad.
- Run the table creation script.
- If you are starting a new installation there will be additional data to populate the tables, depending on your requirements. Otherwise, the tables will be populated by either copying from an Access database, or from a conversion from v1.8 (see below).
- There are two models of user login for StrataBugs 2:
- Each user has their own login to Oracle. Restricted access can be placed on certain tables if necessary (e.g. Userdef).
- All users share the same login credentials but StrataBugs contains additional logins for users.
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 1.8 database
The migration process will be supervised by StrataData, and uses the SBConvert2_0.jar application. The process is documented for user conversions here on the Conversion page. For server based configurations note the following additional points:
- Set up the new schema and run the database v2 table creation script as described above.
- Set up an ODBC connection to both schemas, including the user ID and password in the database connection, since there is no mechanism within the converter to prompt for these.
- Run the converter from the Command Line. Use the following command:
- java -Xmx512m -jar SBconvert2_0.jar
- Note that the above allocates a maximum of 512Mb of memory to the java process: you may need more than this for very large database conversions.
- You may need to qualify the java command so that you are running on the 32-bit java platform, if you are using a 64-bit system. This is because we have noted differences in the way the ODBC drivers work. To run the 32-bit JRE you may use a command like this:
- "C:\Program Files (x86)\java\jre7\bin\java" -Xmx512m -jar SBconvert2_0.jar
- The command line messages can be used in conjunction with the log file to help with troubleshooting the migration process.
Connection errors
You may get errors connecting to the data sources when trying to use the conversion program. This can be due to a mis-match between the application and the data source, or the underlying driver. For instance, if you start the conversion application using a 64-bit java runtime environment (you can check this using the java -version command), then you will get the following error when attempting to connect to a 32-bit data source:
If, however you attempt to connect to a 64-bit data source for the Oracle driver you may get this error:
The solution in both these cases is to ensure that you have set up a 32-bit data source, and are running the application under the 32-bit JRE.
If you get this error:
Then you have successfully connected to a database, but the schema (tables) are not present, or unreadable by the connected user. The table PREF_SYSTEM is a table only found in StrataBugs v2. You may get this error in Oracle databases if either the SCHEMA is not set to the table owner in the user's connection settings, OR it may be that the user does not have permission to access the v2 schema tables. To determine the source of the error, connect to an SQL prompt using the user's credentials, and try a SELECT query on the schema.PREF_SYSTEM table. If you get a "Table or view does not exist" error then you need to grant permission (through the role). If you ARE able to query the table, then the schema needs to be set correctly in the user's connection settings.
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 the 'new' v2.0 charts with a hard-coded template. 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_0.jar jsbugs.ChartGen
adding the following parameters:
- driver=? - usually this will be "odbc"
- host=? - the data source name
- instance=? - the database instance name
- instanceLogin=? - the database user name
- password=? - the database password
- path=? - the folder in which the generated charts will be stored. E.g. "D:\sbugs\ChartGen". This must be an existing folder.
- sbugslogin=? - StrataBugs user abbreviation (e.g. "SYS").
- sbugspassword=? - StrataBugs password for user (omit this parameter if the StrataBugs password is the same as the database password).
- project=? - The name of a StrataBugs project to use. This is useful for testing the process on a subset of wells. Omit this parameter to generate charts for the entire database. Enclose the project name in double quotes if it contains spaces.
When you are satisfied with the parameter setup, you can create the windows batch file "ChartGen.bat." Example contents:
D:
cd "\sbugs\Training Course\SBugs2\StrataBugs-2"
"C:\Program Files (x86)\Java\jre7\bin\java.exe" -Xmx1024m -cp jsbugs2_0.jar jsbugs.ChartGen driver=odbc host=SBUGS2-0 instance=SBUGS instancelogin=DBA password=system sbugslogin=SYS path="D:\sbugs\ChartGen" > 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; new charts will be added for any new wells.