Skip Headers

Oracle® Procedural Gateway and Tools for IBM MQSeries Installation and User's Guide
Release 9.2.0.1.0 for MS Windows
Part No. A96197-01
Go To Table Of Contents
Contents
Go To Index
Index

Previous Next

C
Gateway Initialization Parameters

The gateway has its own initialization parameters (described in this appendix) and supports the initialization parameters for procedural gateways that are described in the Oracle Open Gateway Guide for SQL-Based and Procedural Gateways.

The parameters in this appendix are:

Gateway Initialization File

The gateway initialization file is named initsid.ora.  A default initialization file is created in the directory ORACLE_HOME\pg4mqseries\admin during the installation of the gateway software.

Gateway Parameters

HS_DB_DOMAIN

Default value: None
Range of values: None
Syntax: SET HS_DB_DOMAIN = domain_name

HS_DB_DOMAIN is used only 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 created in the Oracle integrating server to connect to the queue manager.

HS_DB_NAME

Default value: None
Range of values: None
Syntax: SET HS_DB_NAME = database_name

HS_DB_NAME is used only when the Oracle integrating server initialization parameter GLOBAL_NAMES is set to TRUE.

In this case, the value of database_name is the database name of the database link created in the Oracle integrating server to connect to the queue manager.

LOG_DESTINATION

Default value: pg4mqs_PID.log (PID is the process ID of the gateway)
Range of values: None
Syntax: SET LOG_DESTINATION = log_file

LOG_DESTINATION specifies the full path name of the gateway log file. 

AUTHORIZATION_MODEL

Default value: RELAXED
Range of values: RELAXED or STRICT
Syntax: SET AUTHORIZATION_MODEL = {RELAXED|STRICT}

AUTHORIZATION_MODEL defines the authorization model for the gateway user.  Specify AUTHORIZATION_MODEL as:

RELAXED specifies that authorizations that are granted to the effective user ID of the gateway by the queue manager are the only associations that an Oracle application has. 
STRICT specifies that the Oracle user ID and password (that are provided when a database link is created), or the current user ID and password (when the Oracle user ID and password are not provided), is checked against the local or network password file.

Refer to " Security Models" for more information about effective user IDs.

QUEUE_MANAGER

Default value: None
Range of values: None
Syntax: SET QUEUE_MANAGER = manager_name

QUEUE_MANAGER, a required parameter, specifies the name of the queue manager that the gateway connects to at logon time.  The effective user ID of the gateway should have the correct user privileges and/or should be authorized to connect to this queue manager.  Specify manager_name using the following rules:

  • 1 to 48 alphanumeric characters in length

  • no leading or embedded blank characters

  • trailing blank characters are permitted

Refer to " Security Models" for more information about effective user IDs.

TRACE_LEVEL

Default value: 0
Range of values: 0 to 7
Syntax: SET TRACE_LEVEL = level

TRACE_LEVEL controls whether tracing information is collected as the gateway runs.  When set to collect information, the trace data is written to the log file that is specified by the LOG_DESTINATION parameter.  Specify level as an integer from 0 to 7, which is the sum of the desired trace values:

0 specifies that no tracing is done. 
1 specifies that general tracing is done.  This includes the user ID that is used to logon to the MQSeries queue manager, the name of the queue manager, the gateway transaction mode, security mode, and so on.
2 specifies that tracing is done for all MQI calls that are issued by the gateway.
3 specifies that tracing is a combination of level 1 and 2.
4 specifies that tracing is done for all parameter values passed to, or received from, the MQI calls issued by the gateway.
5 specifies that tracing is a combination of levels 1 and 4.
6 specifies that tracing is a combination of trace level 2 and 4.
7 specifies that tracing is a combination of trace levels 1, 2, and 4.

For more information about MQI calls, refer to IBM publications.

TRANSACTION_LOG_QUEUE

Default value: None
Range of values: None
Syntax: SET TRANSACTION_LOG_QUEUE = tx_queue_name

TRANSACTION_LOG_QUEUE specifies the name of the queue for logging transaction IDs.  Specify tx_queue_name using the following rules:

  • 1 to 48 alphanumeric characters in length

  • no leading or embedded blank characters

  • trailing blank characters are permitted

Refer to "Creating a Transaction Log Queue" for more information.

TRANSACTION_MODEL 

Default value: SINGLE_SITE
Range of values: COMMIT_CONFIRM or SINGLE_SITE
Syntax: SET TRANSACTION_MODEL = {COMMIT_CONFIRM|SINGLE_SITE}

TRANSACTION_MODEL defines the transaction mode of the gateway.  Specify TRANSACTION_MODEL as:

COMMIT_CONFIRM specifies that the gateway can participate in transactions when queues belonging to the same MQSeries queue manager are updated.  At the same time, any number of Oracle databases are updated.  Only one gateway with the commit-confirm model can join the distributed transaction, because the gateway operates as the focal point of the transaction.

When this value is specified, you must also set the RECOVERY_USER, RECOVERY_PASSWORD, and TRANSACTION_LOG_QUEUE parameters.

SINGLE_SITE specifies that the gateway can participate in a transaction only when queues belonging to the same MQSeries queue manager are updated.  An Oracle application can select, but not update, data at any Oracle database within the same transaction that accesses MQSeries.

TRANSACTION_RECOVERY_PASSWORD

Default value: *
Range of values: An asterisk (*), which indicates that the parameter must be encrypted, or any valid password
Syntax: SET TRANSACTION_RECOVERY_PASSWORD = rec_password

or

SET TRANSACTION_RECOVERY_PASSWORD = *

TRANSACTION_RECOVERY_PASSWORD specifies the password of the user that the gateway uses to start recovery of a transaction.  The default value is set to an asterisk (*), and this asterisk designates that the value of this parameter is stored in an encrypted form in a separate password file.  To specify or change a valid password for encrypted gateway parameters, you need to use the gateway utility pg4mqpwd to do the work.  For more information, refer to "Using the pg4mqpwd Utility" on page C-9.

This TRANSACTION_RECOVERY_PASSWORD parameter is required only when TRANSACTION_MODEL is set to COMMIT_CONFIRM.  Refer to "Creating a Transaction Log Queue" for more information.

Passwords in the Gateway Initialization File

The gateway uses userids and passwords to access the information in the remote database on the IBM MQSeries server.  Some userids and passwords must be defined in the Gateway Initialization File to handle functions such as resource recovery.  In a security conscious environment, plain-text passwords are deemed insecure when they are accessible in the Initialization File.  A new encryption feature has been added to the gateway to help make such passwords more secure.  The pg4mqpwd utility can be used to encrypt passwords that would normally be stored in the Gateway Initialization File.  Using this feature is optional, but highly recommended by Oracle Corporation.  With this feature, passwords are no longer stored in the Initialization File but are stored instead in a password file in an encrypted form, thus making the information more secure.  Read the next section to learn how to use this feature.

Using the pg4mqpwd Utility

The pg4mqpwd utility is used to encrypt passwords that would normally be stored in the Gateway Initialization File.  The utility works by reading the Initialization File and looking for parameters with a special value.  The value is the asterisk (*).  This asterisk designates that the value of this parameter is stored in an encrypted form in another file.  Following is a sample section of the Initialization File with this value:

TRANSACTION_RECOVERY_PASSWORD=*

The Initialization File is first edited to set the value of the parameter to "*".  Then the pg4mqpwd utility is run, specifying the gateway SID on the command line.  The utility will read the Initialization File and prompt the user to enter the values to be encrypted.

The syntax of the command is: pg4mqpwd [gateway_sid]

Where [gateway_sid] is the SID of the gateway.

Following is an example run, assuming a gateway SID of pg4mqs92:

% pg4mqpwd pg4mqs92
ORACLE Gateway Password Utility (pg4mqseries) Constructing password file for Gateway SID pg4mqs92
Enter the value for TRANSACTION_RECOVERY_PASSWORD
welcome
%

In this example, the parameter TRANSACTION_RECOVERY_PASSWORD is identified as requiring encryption.  The user enters the value (for example, welcome) and presses enter.  If more parameters require encryption, then you will be prompted for their values.  The encrypted data is stored in the pg4mqseries/admin directory.


Note:

It is important that the ORACLE_HOME environmental variable be pointing to the correct gateway home in order to ensure that the correct Gateway Initialization File is read.

TRANSACTION_RECOVERY_USER

Default value: None
Range of values: Any valid operating system user ID that is authorized by MQSeries Manager (MQM)
Syntax: SET TRANSACTION_RECOVERY_USER = rec_user

TRANSACTION_RECOVERY_USER specifies the username that the gateway uses to start recovery of a transaction.  This parameter is required only when AUTHORIZATION_MODEL is set to STRICT, and TRANSACTION_MODEL is set to COMMIT_CONFIRM.  Refer to "Creating a Transaction Log Queue" for more information.


Previous Next
Oracle Logo
Copyright © 2001, 2002 Oracle Corporation

All rights reserved
Go To Table Of Contents
Contents
Go To Index
Index