Friday, March 4, 2011

Add External Help to the Application

Call an external web-page as Help for pages in the application.


Ø  External web-pages from Help documents
Ø  Resource Bundle
Ø  adf-settings.xml file
Ø  Java Class
o   extends the ResourceBundleHelpProvider

Resource Bundle

Create a properties file that contains value-pairs, the topic ID and help text for each help topic. The topic ID must be made up of the following parts:
Ø  Prefix
o   Any prefix that will identify this application help
Ø  Name
o   Must be unique
Ø  Help Type
For example, a topic ID might be PASYS_HOMEPAGE_DEFINITION.
The Resource Bundle holds the value pairs
1.       Help Topic
a.       Help topic will have a suffix of _DEFINITION
2.       Help Text
a.       This appears when you mouse over the help icon
PASYS_HOMEPAGE_DEFINITION=  Apportionment Sub-System Home Page, Press for Help


Create the file ADF-Settings.xml under Application Resources \Descriptors\ADF-WEB-INF if it does not already exist
Register the resource bundle created in the previous step as a help provider in the adf-settings.xml file
<?xml version="1.0" encoding="windows-1252" ?>
<adf-settings xmlns=""
<adf-faces-config xmlns="">
  <help-provider prefix = "PASYS_HELP_">
The Above code assumes
Ø  PASYS_HELP_ as the Help-Provider prefix
Ø  view.resources.ViewControllerBundle is the Help “Resource Bundle”

Java Class

Create a Java Class
Ø  Name
o   PasysHelpProvider
Ø  Package
Ø  Extends
o   ResourceBundleHelpProvider

Add Help to Pages

Create a value pair in the properties file for each page to add Help
Ø  Help Topic
o   Include suffix _DEFINITION
Ø  Help Text
Add the Help Topic to the HelpTopicId of the component to contain the Help link

The HelpTopicId is the first value (Help Topic) in the pair minus the _DEFINITION e.g. PASYS_HELP_HOMEPAGE (from the example above)
The HelptopicId is found under the Appearance tab of the Properties. The topic on the Panel Header in this instance. A help icon will now appear beside the Panel Header Label when the page is invoked

At this point the Help Icon will display the help text only on mouse over when the page is invoked

External URL

To call an external web-page to display the help we must override the super class in our method created above.
The getExternalUrl method currently returns Null all the time, so we override it and we hard-wire in the page we wish to display.
The external web-pages have been created in the help folder at ViewController\Web Content
The address is then /pasys/faces/help/ where pasys is the Java EE web-context root
import javax.faces.component.UIComponent;
import javax.faces.context.FacesContext;
public class PasysHelpProvider extends ResourceBundleHelpProvider {
  public PasysHelpProvider() {}
  private String PASYS_HOME_PAGE = "/pasys/faces/help/HomePage.htm";
      protected String getExternalUrl(FacesContext context, UIComponent component, String topicId)
      if (topicId == null)
       return null;
      if (topicId.contains ("PASYS_HELP_HOMEPAGE"))
         return PASYS_HOME_PAGE;
      return null;                                 

For every help-page we add a private string and an “if statement” as shown above for the Home Page.

We use the “contains” suffix to ensure we capture the help topic correctly.
To display the Help Page press the Help icon, the external page will be displayed in a separate window.

Monday, February 28, 2011

Install & Configure Oracle Database Gateway for MQ

This is a digression from the usual entry but it took me a while to install and configure the gateway and I think it may be useful to anyone trying it in the future. The documentation in the main is excellent but there are a few instructions that my installation required that were not documented.

Oracle Database Gateway for MQ (64-bit Linux installation)

I installed the Gateway on a separate server from the database. The WebSphere MQ was installed on it's own server also.  

Basic Requirements

·         X-Windows server (e.g. Cygwin, Xming)
·         Ssh client software (e.g. putty)
· file.
·         mqc6_6.0.2.10_linuxx86-64.tar
·         Oracle 11GR2 database installed

Installation documents

IBM MQ Client

Installation Steps

·         Install MQ Client
·         Install Procedural Gateway
·         Configure Gateway

Install MQ Client

N.B. Deploy the samples or we can’t test the Queue


  • Log in as root.
  • Create the directories to hold the MQ code and working data.
o   The WebSphere MQ is installed in /opt/mqm.
The working data uses /var/mqm
·         Create a user ID and group ID  mqm.
o   Set the users home directory to /var/mqm
  • Change into the unzipped MQ product directory  
    • Run the script.
./ -accept
You must accept the license agreement before you can proceed with the installation.
  • Use the rpm -ivh command to install each component that you require.
o   rpm -ivh MQSeriesRuntime-6.0.2-10.x86_64.rpm MQSeriesClient-6.0.2-10.x86_64.rpm MQSeriesSamples-6.0.2-10.x86_64.rpm


Go to /opt/mqm/samp/bin
·         CHANNEL1 = the server-connection channel defined on the MQ server
·         TCP = the communications protocol.
·         server-hostname = the TCP/IP host name of the server.
·         port =port MQ is listening on (Default 1414)
set MQSERVER=‘CHANNEL1/TCP/server-hostname(port)’ –Use quotes in Linux

Browse the queue
amqsgbrc <<Queue Name>> <<Queue Manager>>

Output (Successful)
Sample AMQSGBR0 (browse) start
<<Queue Manager>>
Messages for <<Queue Name>> (ctrl+C to stop or just let it browse the msgs)
1 <RFH >
2 <RFH >

Install Procedural Gateway

Log-in as the user intended to own the gateway software
Unzip the file.


Determine where the WebSphere MQ queue manager runs.
Local system                      Oracle SID = dg4mqs
Remote system                                Oracle SID = dg4mqc
We require the
1.       MQ Queue Manager
2.       MQ Channel
3.       MQ server-host IP
4.       MQ Port


Navigate to the unzipped folder and  ./runInstaller to run the GUI installer
For installation instructions use section 5 of the Oracle Installation guide

Configure Oracle Procedural Gateway

The gateway is installed and preconfigured using default values for the gateway SID, directory names, file names, and gateway parameter settings.
 The default SID values are:
·         dg4mqs               
o    The default SID that is used when the gateway resides on the same system as the WebSphere MQ software.
·         dg4mqc
o    The default SID that is used when the gateway resides on a different system than the WebSphere MQ software. 
 A basic gateway initialization file is also installed, and values in this file are set based on the information entered during the installation phase.


We want to make 2 changes to the Listener File.
1.       We want to an add an EXTPROC entry to listen for the external library
a.       This will allow the database to connect to the correct library
2.       We want to add the LD_LIBRARY_PATH to the dg4mqc entry
a.       This will allow us to use the correct 64-bit library and eliminate the error
(ADDRESS=(PROTOCOL=tcp)(HOST= * establish * dg4mqc * 12518
TNS-12518: TNS:listener could not hand off client connection
 TNS-12547: TNS:lost contact
  TNS-12560: TNS:protocol adapter error
   TNS-00517: Lost contact
    Linux Error: 32: Broken pipe

Example Listener
 Oracle_Home = /home/oracle/product/11.2.0/tg_1
   (SID_LIST =
            (SID_NAME= PLSExtProc)
            (PROGRAM= extproc)
      (ADDRESS = (PROTOCOL = TCP)(HOST = = 1521))


ADR_BASE_LISTENER = /home/oracle/product/11.2.0/tg_1
To test the dg4mqc programme is pointing to the correct library at the command line run
$ dg4mqc

Set the LD_LIBRARY_PATH and rerun

The database server needs an entry in the tnsnames.ora to connect to the gateway (via database link)
      (ADDRESS = (PROTOCOL = TCP)(HOST = = 1521))
      (SERVICE_NAME = dg4mqc)

Database Link

A connection to the gateway is established through a database link when it is first used in an Oracle session.
The AUTHORIZATION_MODEL parameter is set to RELAXED and as such no username or password are required.

Alias Library

Create the Oracle Database Gateway for WebSphere MQ alias library, libdg4mq, using the Oracle Database Gateway for WebSphere MQ deployment scripts. During installation, the appropriate shared library name is defined ORACLE_HOME/dg4mq/admin/deploy/pgmobj.sql on UNIX
For a remote model, the shared library is used.
For example:

Preparing the Production Oracle Database

Before you can compile MIPs on a production Oracle database, the following PL/SQL packages must be present on the production Oracle database:
o    Installed as part of a typical database creation
·         PGM, PGM_BQM, PGM_SUP, and UTL_PG
o    These packages are shipped with your Oracle Database Gateway for WebSphere MQ and are present in ORACLE_HOME/dg4mq/admin/deploy
Copy the scripts in this directory to the database server OR configure a connection to the database server
To install the packages we use the script pgmdeploy.sql. The pgmdeploy script connects as scott/tiger so we need to edit the script and change this to a valid user, include the database connection script here also.  Change the line connect SYS/&INPASS2 as sysdba to include the database connection string connect SYS/&INPASS2@oracl as sysdba.
Set the Oracle_SID
         sqlplus /nolog @pgmdeploy.sql
The PQM_UTL8 procedure relies on the Visual workbench Repository so it will be invalid.

Testing the MQ connection

Reload the listener on the Gateway server
$ lsnrctl reload
Use the test.sql script from the ORACLE_HOME/dg4mq/sample directory on the gateway.
Edit the file to change the lines
  objdesc.objectname := '<<Your Queue name>>';
  objdesc.dblinkname := '<<Your DB Link>>';

From SQL prompt execute the script SQL> @test


No trace files will be written for MQ unless there has been a valid attempt to connect to MQ
The 3 Issues I encountered were
1.       Port not open on the firewall     -No Trace file written
2.       LD_LIBRARY_PATH not set/pointed to correct library      - No Trace file written
3.       Library not declared in an exproc entry in the listener     -Trace file written