7
Configuration

Step 1: Choose a system ID for the gateway

The gateway SID is a string of 1 to 64 alphanumeric characters that identifies a gateway instance.  The SID is used in the gateway boot file and as part of the file name for the gateway parameter file.  Choose a SID different from the default SID and different from pg4mqs92 and pg4mqc92.

You need one gateway instance, and therefore one gateway SID, for each queue manager you want to access.  If you want to access two different queue managers, then you need two gateway SIDs, one for each instance of the gateway.  Or, if you have one queue manager and want to access it sometimes with one set of gateway parameter settings and at other times with different gateway parameter settings, then you can do so by having multiple gateway SIDs for the one queue manager.

Step 2: Customize the gateway boot file

The gateway boot file initializes environment variables.  The boot file is required, and a default boot file is installed by the Oracle Universal Installer:

Gateway Running Mode	Boot File Path
As MQSeries server	ORACLE_HOME/pg4mqseries/admin/initsid.gtwboot
As MQSeries client	ORACLE_HOME/pg4mqseries/admin/initsid.gtwboot

where sid is the default SID of pg4mqs92 or pg4mqc92.  If you chose a SID other than the default, then rename this file using the SID you chose in Step 1.  If you have multiple gateway instances, then copy the default boot file as necessary, and rename each gateway instance using the SID of each instance.

The default boot files contain the following required entries:

Gateway Running in MQSeries Server Configuration

GATEWAY_SID=gateway_sid
SERVER_PATH=gateway
LOG_DESTINATION=log_file
LD_LIBRARY_PATH=mqseries_directory

where:

gateway_sid	specifies the SID of the gateway and matches the SID specified in the connect descriptor for the gateway in the tnsnames.ora file.  Refer to "Configuring Oracle Net for the Oracle Integrating Server" for more information about tnsnames.ora.
gateway	specifies the full path name of the gateway executable file.
log_file	specifies the full path name of the gateway bootstrap program log file.
mqseries_directory	specifies the directory where the MQSeries libraries (provided by IBM) are installed.  If the libraries were not installed under the default directory of /usr/lib, then use mqseries_directory to specify the correct directory name.

Gateway Running in MQSeries Client Configuration

GATEWAY_SID=gateway_sid
SERVER_PATH=gateway
LOG_DESTINATION=log_file
LD_LIBRARY_PATH=mqseries_directory
MQSERVER=channel
MQCCSID=character_set

where:

gateway_sid	specifies the SID of the gateway and matches the SID specified in the connect descriptor for the gateway in the tnsnames.ora file.  Refer to "Configuring Oracle Net for the Oracle Integrating Server" for more information about tnsnames.ora.
gateway	specifies the full path name of the gateway executable file.
log_file	specifies the full path name of the gateway bootstrap program log file.
mqseries_directory	specifies the directory where the MQSeries libraries (provided by IBM) are installed.  If the libraries were not installed under the default directory of /usr/lib, then use  mqseries_directory to specify the correct directory name.
channel	specifies the location of the MQSeries server and the communication method to use.  The channel format is: channel_name/connection_type/hostname [(port_number)]. For example: MQSERVER=CHAN9/TCP/dolphin(1425) Refer to IBM publications for more information about the MQSERVER environment variable. Note: The channel name and connection type must entered in CAPITAL LETTERS.
character_set	specifies the coded character set number used by the gateway when communicating with the MQSeries queue manager.  This is an optional parameter.  This parameter is set only if the computer that is running the MQSeries queue manager uses a different encoding scheme than the computer that runs the gateway.  When set, the value of character_set is used by the MQSeries client software on the gateway's computer to convert the data. The value specified for character_set affects communication only between the gateway and the MQSeries queue manager.  The message data sent or received by your application is not affected. Refer to IBM publications for more information.

Step 3: Customize the Gateway Initialization File 

The Gateway Initialization File (sid{{/emphasis}}{{emphasis role='Bold'}}.ora{{/emphasis}}"inittalic>sid.ora) supports all procedural gateway initialization parameters described in the Oracle Open Gateway Guide for SQL-Based and Procedural Gateways and in Appendix C, " Gateway Initialization Parameters".  The initialization file must be available when the gateway is started. 

During installation, a default initialization file is created in $ORACLE_HOME/pg4mqseries/admin/initsid.ora, where sid is the default SID of pg4mqs92 or pg4mqc92.  If you chose a SID other than the default, then rename this file using the SID you chose in Step 1: Choose a system ID for the gateway.  Customize the default initialization file as necessary.

The following entries might appear in an initialization file:

SET LOG_DESTINATION=log_file
SET HS_DB_NAME=database_name
SET HS_DB_DOMAIN=domain_name
SET QUEUE_MANAGER=manager_name
SET AUTHORIZATION_MODEL=auth_model
SET TRANSACTION_MODEL=tx_model
SET TRANSACTION_LOG_QUEUE=tx_queue_name
SET TRANSACTION_RECOVERY_USER=rec_user
SET TRANSACTION_RECOVERY_PASSWORD=rec_password
SET TRACE_LEVEL=0

Note: Refer to Oracle9i Net Services Administrator's Guide and Oracle9i Net Services Reference Guide for additional information.

where:

log_file	specifies the full path name of the gateway log file.
database_name	is only used when the Oracle integrating server initialization parameter GLOBAL_NAMES is set to TRUE.  In this case, the value of database_name is the name of the database link that was created in the Oracle integrating server to connect to the gateway.  It is 1 to 8 characters long.
domain_name	is only used when the Oracle integrating server initialization parameter GLOBAL_NAMES is set to TRUE.  In this case, the value of domain_name is the domain name of the database link that was created in the Oracle integrating server to connect to the queue manager.
manager_name	is the name of the MQSeries queue manager to access.
auth_model	is the authorization model to use.  The default is RELAXED.  Refer to Chapter 8, " Gateway Running Environment" for more information about security models.
tx_model	is the transaction model to use.  The default is SINGLE_SITE.  Refer to Chapter 8, " Gateway Running Environment" for more information about transaction models.
tx_queue_name	is the name of the queue for logging transaction IDs for distributed transactions.  This is only used when tx_model is set to COMMIT_CONFIRM.  Refer to Chapter 8, " Gateway Running Environment" for more information about transaction models.
rec_user	specifies the user name that the gateway uses to start recovery of a distributed transaction.  This is only used when auth_model is set to STRICT and tx_model is set to COMMIT_CONFIRM.  Refer to Chapter 8, " Gateway Running Environment" for more information about security models.
rec_password	specifies the password of the user name that the gateway uses to start recovery of a distributed transaction.  Refer to "TRANSACTION_RECOVERY_PASSWORD" on page C-8 for more password information and to Chapter 8, " Gateway Running Environment" for more information about security models.

Step 1: Configure the Oracle Net TNS listener for the gateway

Two entries must be added to the listener.ora file:

• a list of Oracle Net addresses for the TNS listener to listen on

• the gateway process that the TNS listener should start in response to incoming connection requests

  
  

  Note: The TNS listener and the gateway must reside on the same node.  If you already have a TNS listener up and running on the node, then you may want to make the following changes (in Steps 1 and 2) to your existing listener.ora and tnsnames.ora files. After making the changes, you can reload the changes by running the "reload" subcommand in the "lsnrctl" utility without shutting down the TNS listener.

  
  

Entry of Oracle Net Addresses for the TNS Listener

If you are using Oracle Net and the TCP/IP protocol adapter, then the syntax of the entry in the listener.ora file is:

LISTENER=
  (ADDRESS_LIST=
      (ADDRESS= 
          (PROTOCOL=TCP)
          (HOST=host_name)
          (PORT=port_number)
       )
  )

where:

host_name	is the name of the computer where the gateway is installed.
port_number	specifies the IP port number used by the TNS listener.  If you have other listeners running on host_name, such as the listener of an Oracle integrating server on the same computer, then the value of port_number must be different from the other listeners' port numbers.

If you are using Oracle Net and the interprocess socket call (IPC) protocol adapter, the syntax of the entry in listener.ora file is:

LISTENER=
  (ADDRESS_LIST=
     (ADDRESS= 
         (PROTOCOL=IPC)
         (KEY=key_name)
     )
   )

where:

IPC	specifies that the protocol used for connections is IPC.
key_name	is the unique user-defined service name.

Entry for the Gateway

To direct the TNS listener to listen for a gateway instance in response to incoming connection requests, add an entry to the listener.ora file using the following syntax:

SID_LIST_LISTENER=
   (SID_LIST=
      (SID_DESC=
          (SID_NAME=gateway_sid)
          (ORACLE_HOME=gateway_directory)
          (PROGRAM=driver)
       )
    )

where:

gateway_sid	specifies the SID of the gateway and matches the gateway SID specified in the connect descriptor entry in the tnsnames.ora file.  Refer to "Configuring Oracle Net for the Oracle Integrating Server".
gateway_directory	specifies the gateway directory where the gateway software resides.
driver	this is the name of the executable file that initializes the gateway environment using the boot file and that starts the gateway.  If the gateway uses a local MQSeries server, then the file name is pg4mqs92drv; the file name is pg4mqc92drv if the gateway is run as an MQSeries client to access a remote MQSeries server.

When adding an entry for multiple gateway instances, add the entry to the existing SID_LIST syntax:

SID_LIST_LISTENER=
 (SID_LIST=
      (SID_DESC=.
                .
                .
      )
      (SID_DESC=.
                .
                .
      )
      (SID_DESC= 
          (SID_NAME=gateway_sid)
          (ORACLE_HOME=gateway_directory)
          (PROGRAM=driver)
       )
  )

The following is an example of an entry made to the listener.ora file:

(SID_DESC =
         (SID_NAME=pg4mqs92)
         (ORACLE_HOME=/oracle/app/oracle/product/pg4mqs92)
         (PROGRAM=pg4mqs92drv)
)

Refer to Oracle9i Net Services Administrator's Guide and Oracle9i Net Services Reference Guide for more information about changing listener.ora. 

Step 2: Stop and start the TNS listener for the gateway

The TNS listener must be started or reloaded to initiate the new settings.

Note: If you already have a TNS listener up and running on the Oracle integrating server where the gateway is installed, then you may want to make changes to your existing listener.ora and tnsnames.ora files.  After making the changes, you can reload the changes by running the "reload" subcommand in the "lsnrctl" utility without shutting down the TNS listener. Refer to the Entry of Oracle Net Addresses for the TNS Listener after "Step 1: Configure the Oracle Net TNS listener for the gateway".

• Set the gateway directory name:

  If you are using the Bourne or Korn shell, then enter:

  $ ORACLE_HOME=gateway_directory;export ORACLE_HOME
  
  

  If you have the C shell, then enter:

  $ setenv ORACLE_HOME gateway_directory
  
  

  where gateway_directory specifies the directory where the gateway software is installed.

• If the listener is already running, then use the lsnrctl command to reload the listener with the new settings:

  $ cd $ORACLE_HOME/bin
  $ ./lsnrctl reload your_listener_name
  
  

  where ORACLE_HOME specifies the directory where the gateway software is installed.

• Check the status of the listener with the new settings:

  $ ./lsnrctl status your_listener_name
  
  

  The following is an example of output from a lsnrctl status check:

Connecting to (ADDRESS=(PROTOCOL=IPC)(KEY=ORAIPC))
STATUS of the LISTENER
------------------------
Alias                     LISTENER
Version                   TNSLSNR for Solaris: version 9.2.0.1.0 - Production
Start Date                21-AUG-99 18:16:10
Uptime                    0 days 0 hr. 2 min. 19 sec
Trace Level               off
Security                  OFF
SNMP                      OFF
Listener Parameter File   /oracle/app/oracle/product/pg4mqs901/network/admin/listener.ora
Listener Log File         /oracle/app/oracle/product/pg4mqs901/network/log/listener.log
Services Summary...
  pg4mqs90            has 1 service handler(s)
The command completed successfully

In the example above, pg4mqs90 is the default SID value that was assigned during installation.  You can use any valid ID for the SID, or keep the default.

TCP/IP Example

An Oracle integrating server accesses the gateway using Oracle Net and the TCP/IP protocol adapter.  The syntax of the connect descriptor entry in tnsnames.ora is:

tns_name_entry=
  (DESCRIPTION=
     (ADDRESS=
          (PROTOCOL=TCP)
          (HOST=host_name)
          (PORT=port_number)
     )
     (CONNECT_DATA=
     (SID=gateway_sid)
     )
     (HS=OK)
) 

where:

tns_name_entry	is the tns_name_entry of the CREATE DATABASE LINK statement.  Refer to "Creating Database Links" for more information.
TCP	specifies that the protocol used for connections is TCP/IP.
port_number	matches the port number used by the Oracle Net TNS listener that is listening for the gateway.  The TNS listener's port number can be found in the listener.ora file that is used by the TNS listener.  Refer to "Entry of Oracle Net Addresses for the TNS Listener".
host_name	specifies the computer on which the gateway is running.  The TNS listener's host name can be found in the listener.ora file used by the TNS listener that is listening for the gateway.  Refer to "Entry of Oracle Net Addresses for the TNS Listener".
gateway_sid	specifies the SID of the gateway and matches the SID specified in the listener.ora file of the TNS listener that is listening for the gateway.

IPC Example

An Oracle integrating server accesses the gateway using Oracle Net and the IPC protocol adapter.  The syntax of the connect descriptor entry in tnsnames.ora is:

tns_name_entry=
    (DESCRIPTION=
        (ADDRESS=
        (PROTOCOL=IPC)
        (KEY=key_name)
    )
    (CONNECT_DATA=
        (SID=gateway_sid)
    )
     (HS=OK)
  ) 

where:

tns_name_entry	is the tns_name_entry of the CREATE DATABASE LINK statement.  Refer to "Creating Database Links" for more information.
IPC	specifies that the protocol used for connections is IPC.
key_name	is the service name.
gateway_sid	specifies the SID of the gateway and matches the SID specified in the listener.ora file of the TNS listener that is listening for the gateway.

Step 1: Choose a repository server

A repository server is an Oracle integrating server on which the Visual Workbench repository is installed. 

Step 2: Locate the installation scripts

The Visual Workbench repository installation scripts are installed with the Visual Workbench.  If the repository is to be installed on the same computer as Visual Workbench, then your repository server already has all the required installation scripts.  Proceed to step 3.

1. Create a directory on the repository server that is to be the script directory.  For example:

   $ mkdir $ORACLE_HOME/pg4mqseries/admin/repo
   $ chmod 777 $ORACLE_HOME/pg4mqseries/admin/repo
   
   

2. Use a file transfer program to transfer the repository zip file (reposXXX.zip, where XXX is the release number) or move all script files with the suffix .sql from the script file directory (NT=%ORACLE_HOME%\pg4mqvwb\server\admin) on the Visual Workbench computer to the script file directory on the repository server computer.

Step 3: Ensure the UTL_RAW package is installed

All data mapping packages generated by the Visual Workbench use the UTL_RAW package, which provides routines for manipulating raw data.

From SQL*Plus, as user SYS, issue the following statement:

SQL> DESCRIBE UTL_RAW

If the DESCRIBE statement is successful, then your repository server already has UTL_RAW installed, and you can proceed to step 4. 

If the DESCRIBE statement fails, then install UTL_RAW:

From SQL*Plus, as user SYS, run the utlraw.sql and prvtrawb.plb scripts that are in directory ORACLE_HOME/rdbms/admin.  You must run the utlraw.sql script first. 

SQL> @utlraw.sql
SQL> @prvtrawb.plb

Step 4: Ensure the DBMS_OUTPUT package is enabled

The sample programs and installation verification programs on the distribution CD-ROM use the standard DBMS_OUTPUT package.

From SQL*Plus, as user SYS, issue the following statement:

SQL> DESCRIBE DBMS_OUTPUT

If the DESCRIBE statement is successful, then your repository server has DBMS_OUTPUT installed, and you can proceed to Step 5.

If the DESCRIBE statement fails, then install DBMS_OUTPUT.  Refer to your Oracle server DBA.

Step 5: Create a database link

Create a database link on your Oracle Production System Server to access the Oracle Procedural GatewayÒ for IBM MQSeries

If you do not already have a database link, then refer to "Administering Database Links" for more information on creating database links.

sqlplus /nolog @pgvwbrepos9.sql

Step 1: Enter the database connection information

Use the default of LOCAL by pressing Return.

Next you are prompted to enter the passwords for the SYSTEM and SYS accounts of the Oracle integrating server.  Press Return after entering each password.

The script stops if any of the information is incorrect.  Verify the information before rerunning the script.

Step 2: Check for existing Workbench Repository

The script checks for an existing Visual Workbench repository and for the data dictionary.  If neither one is found, the script proceeds to Step 3 below.

If the data dictionary exists, then the script stops.  Choose another Oracle integrating server and rerun the script, starting at "Step 1: Choose a repository server ".

If a Visual Workbench repository exists, then the script gives you the following options:

A.  Upgrade the existing private repository to public status and proceed to Step 3 below.

B.  Replace the existing repository with the new private repository and proceed to Step 3 below.

C.  Stop the script.

Step 3: Check for required PL/SQL packages

The script checks for the existence of UTL_RAW, DBMS_OUTPUT, and DBMS_PIPE in the Oracle integrating server.  If this software exists, then the script proceeds to Step 4 below.

The script stops if this software does not exist.  Refer to your Oracle integrating server DBA about the missing software.  After the software is installed, rerun the script.

Step 4: Install the UTL_PG package

The script checks for the existence of the UTL_PG package.  If it does not exist, then the UTL_PG package is installed.  The script proceeds to Step 5 below.

If UTL_PG exists, then you are prompted to reinstall it.  Press Return to reinstall UTL_PG.

Step 5: Create the admin user and all repository tables

This step creates the administrative user for the Visual Workbench repository as PGMADMIN with an initial password of PGMADMIN.  This user owns all objects in the repository. 

After this step, a private Visual Workbench repository, which includes the PGM_SUP,  PGM_BQM, and PGM_UTL8 packages, is created in the Oracle integrating server, which only the user PGMADMIN can access.

Step 6: Create public synonyms and development roles

This is an optional step to change the private access privileges of the Visual Workbench repository.  The private status allows only the PGMADMIN user to have access to the repository.  If you enter N and press Return, then the repository retains its private status.

A public status allows the granting of access privileges to other users besides PGMADMIN.  If you want to give the repository public status, then enter Y and press Return.

sqlplus /nolog @pgvwbremove9.sql

Step 1: Enter the database connection information

Use the default of LOCAL by pressing Return.

Next you are prompted to enter the passwords for the SYSTEM, SYS, and PGMADMIN accounts of the Oracle integrating server.  Press Return after entering each password.

The script stops if any of the information is incorrect.  Verify the information before rerunning the script.

Step 2: Check for existing Workbench repository

Enter "Y" and press Return for the prompt to remove public synonyms and development roles.  This returns the repository to private status.  You can exit the script now by entering "N" and pressing Return, or you can proceed to the next prompt under this step.

If you are certain you want to remove the private repository, then enter "Y" and press Return.  The script removes all repository tables and related packages.