[Contents] [Index] [Info] [Previous] [Next]

CHAPTER 3. The Protocol Adapters

This chapter gives information about the following protocol adapters on OpenVMS:

Mailbox Adapter

DECnet Adapter

TCP/IP Adapter

Bequeath Adapter

Bequeath Listener

Note: This chapter is a supplement to the Understanding SQL*Net guide.

Mailbox Adapter

The Mailbox protocol adapter, or IPC adapter, is automatically configured for use when you install SQL*Net. It can be used for client/server connections when both client and server are on the same OpenVMS node. If the client and server are on different machines, then the connection must take place using DECnet or TCP/IP.

When configuring the TNS listener to listen for mailbox connections, you need to specify a KEY value in LISTENER.ORA for the IPC protocol. The listener then creates a mailbox which listens for connections and creates a system-wide logical name (the same as the KEY value) which translates to this mailbox device. It is via this logical name that clients find the listener's mailbox.

When the SQL*Net parameter AUTOMATIC_IPC is not turned off, connect descriptors specifying the DECnet or TCP/IP protocols for a server on the same node are converted to mailbox connections. If you wish to prevent this, you must include the following line in the TNS_ADMIN:SQLNET.ORA file:

AUTOMATIC_IPC = OFF

Syntax

The following fields must be defined:

(PROTOCOL=IPC)

(KEY=<IPC logical name>)

where:

PROTOCOL The keyword that identifies the specific protocol adapter used; for this protocol, the value is IPC. The value can be entered in either uppercase or lowercase.
KEY The logical name used to connect to the listener via the Mailbox adapter.

Example

This example shows the two fields for the OpenVMS Mailbox adapter.

(PROTOCOL=IPC)

(KEY=ORA_IPC)

Note: A full example of a Mailbox connect descriptor can be found in the file TNS_ADMIN:TNSNAMES_ORA.SAMPLE.

DECnet Adapter

The DECnet protocol adapter provides support for client/server connections using DECnet as a protocol. You can turn SQL*Net support for DECnet on or off via the NetConfig configuration screen (please refer to the Oracle7 for OpenVMS Installation Guide for your platform.)

When configuring the TNS listener to listen for DECnet connections, you need to specify an OBJECT value in the LISTENER.ORA file for the DECnet protocol. The listener registers itself as a DECnet object, using the name specified as the OBJECT value. After the listener is started, you can see the listener object if you issue the following command in the DECnet NCP utility:

NCP> SHOW KNOWN OBJECTS

The DECnet protocol adapter supports both DECnet Phase IV and DECnet Phase V (DECnet/OSI.) However, if you are using DECnet Phase V, depending on your configuration, you may need to use Phase IV aliases in your TNS connect descriptors.

Syntax

The following fields must be defined:

(PROTOCOL=DECNET)

(NODE=node)

(OBJECT=object name)

The following field is optional:

(QUEUESIZE=n)

where:

PROTOCOL Keyword that identifies the specific protocol adapter used; for this protocol, the value is DECNET. The value can be entered in either uppercase or lowercase.
NODE Name of the remote node to which you want to connect. This node must be included in the list of your system's node names. Use the NCP utility to display these parameters by entering the following command in NCP:

					NCP> SHOW KNOWN NODES

OBJECT DECnet object name of the listener to which you want to connect on the specified node. The object is created when the listener starts and is deleted when the listener is stopped. The object of an alias used in the TNSNAMES.ORA file must have a corresponding address in the LISTENER.ORA file; it must have the same object, protocol, and node. An object name must be less that 15 characters in length.
Use upper case when entering object IDs.
QUEUESIZE Parameter that can be used to enlarge the connection mailbox. This parameter is optional; if it is not specified, the default value of 20 is used, allowing twenty DECnet connections to the listener to be pending. If many simultaneous connections are made to the listener, some connection requests may not be received if the DECnet connection mailbox is too small.

Example

In this example, the DECnet connect descriptor specifies a connection to the listener on VAX1 with object name LISTEN1.

(PROTOCOL=DECNET)

(NODE=VAX1)

(OBJECT=LISTEN1)

Note: A full example of a DECnet connect descriptor can be found in the file TNS_ADMIN:TNSNAMES_ORA.SAMPLE.

TCP/IP Adapter

The TCP/IP protocol adapter provides support for client/server connections using TCP/IP as a protocol. You can turn SQL*Net support for TCP/IP on or off via the NetConfig configuration screen (please refer to the Oracle7 for OpenVMS Installation Guide for your platform).

Oracle has based its TCP/IP adapter on the UCX (Digital TCP/IP Services for OpenVMS) driver. Because MultiNet and TCPWare provide UCX emulation, the TCP/IP adapter operates with these products as well.

Note: You must explicitly enable UCX emulation for Multinet or TCPWare If the logical name UCX$DEVICE is defined in your SYSTEM logical name table, this is a good indication that UCX emulation has been enabled. If UCX emulation has not been enabled, please consult your Multinet or TCPWare documentation.

Table 3-1 lists the minimum version of the TCP/IP products which are required with SQL*Net Version 2.3.2.

Protocol Service Supported Version
Digital TCP/IP Services for OpenVMS (UCX) 4.0
Cisco MultiNet 4.0
Process Software TCPware 5.1
Table 3-1 Minimum supported version of TCP/IP products

Newer versions of these products are usually upward-compatible, so that existing applications will continue to work without modification. Thus, they are supported although there is not a formal certification process with each new version of these products.

Syntax

The following fields must be defined:

(PROTOCOL=TCP)

(HOST=hostname)

(PORT=port#)

The following field is optional:

(QUEUESIZE=n)

where:

PROTOCOL Keyword that identifies the specific protocol adapter used; for this protocol, the value is TCP. The value can be entered in either uppercase or lowercase.
HOST Host name or IP address.
PORT# TCP/IP port number of the listener to which you wish to connect on the host specified.
QUEUESIZE Parameter to increase the queue size. This parameter is optional; if it is not specified, the default value of 20 is used. If simultaneous connections are made to the listener, some connection requests may not be received if the listener socket queue size is too small.

Example

In this example, the TCP/IP connect descriptor specifies a listener on the VAX1 host.

(PROTOCOL=TCP)

(HOST=VAX1)

(PORT=1526)

Note: A full example of a TCP/IP connect descriptor can be found in the file TNS_ADMIN:TNSNAMES_ORA.SAMPLE.

Bequeath Adapter

Each database that you wish to connect to with the bequeath adapter must have a command file named ORASRV_BEQ_<sid>.COM in ORA_ROOT:[NETWORK.ADMIN]. For databases created with the Oracle7 RDBMS Release 7.3.2 or later, this command file is generated when you create the database. You must create this command procedure manually for pre-existing databases. Edit the ORA_ROOT:[NETWORK.ADMIN]ORASRV_BEQ_COM.SAMPLE file or execute the command procedure ORA_RDBMS:CREATE_ORASRV_BEQ.COM as follows:

$ @ORA_RDBMS:CREATE_ORASRV_BEQ <ora_db> <sid> <dbname>

where:

<ora_db> is the database administration directory;

<sid> is the SID of the database, for example, PROD; and

<dbname> is the NAME of the database.

For example:

$ @ORA_RDBMS:CREATE_ORASRV_BEQ DKA400:[ORACLE73.DB_PROD] -
  PROD PRODDB

Note: You can find a sample ORASRV_BEQ_COM.SAMPLE file in Appendix C of this manual.

A new mechanism for the bequeath adapter is implemented in this release. This mechanism uses the new BEQUEATH LISTENER process.

Bequeath Listener

The Bequeath Listener is a detached process that runs under a privilege account and serves as an interface between the client process and the server process. The Bequeath Listener listens on a specific mailbox for client requests to connect to the database.

For each request from the client, the Bequeath Listener creates a detached server process and two mailboxes and then sends the client the mailbox names. Then the client can establish a connection to the server process and eventually to the database.

The Bequeath Listener uses a known mailbox name to listen for client requests. This mailbox name is in the format:

ORA_BEQ_READ_MBX_xxxxyyyyyy_n

where:

xxxx is a unique number that is automatically generated when you install the Bequeath Listener.

yyyyyy is the name of the node where the installation occurred.

n is a single-digit number (0-9) that is the Bequeath Listener number.

Files Used by the Bequeath Listener

The Bequeath Listener installation involves the following files:

EXE FILE:

BEQLSNR.EXE is the main Bequeath Listener program.

COM scripts:

<sid>

BEQLSNR_MAIN.COM

This is the main script that controls Bequeath Listener commands. This script is called from NETCONFIGUSER.COM during installation.

CREATE_BEQLSNR.COM

This file creates the BEQLSNR.COM script that is invoked during creation of the Bequeath Listener process and receives one parameter that is a unique ten characters. This script is called from ORA_NETCONFIG_BLD.COM during installation.

LBEQLSNR.COM

This link script links the Bequeath Listener. This script is called from ORA_NETCONFIG_BLD.COM during installation.

ORA_FIND_BEQ_ID.COM

This file generates the unique ten-character bequeath identification.

If no parameter was given to the script, it tries to find the file ORA_BEQ.DAT in the directory sys$system for the current node. If the file is not in that directory, a unique identifier is generated for this installation. After creating the file ORA_BEQ.DAT in SYS$SYSTEM, a file ORA_BEQ.DAT is created in the directory ORA_INSTALL that contains the unique bequeath identification for this installation.

If no parameter was given, then the file ORA_INSTALL:ORA_BEQ.DAT is searched for the unique identification. The logical name ORA_BEQ is defined after running this script. This script is called from NETCONFIGUSER.COM and ORA_NETCONFIG_BLD.COM.

STARTUP_BEQLSNR.COM

Startup the Bequeath Listener as a detached process. The script looks for the logical ORA_BEQ_NUM_OF_LISTENERS that defines the number of Bequeath Listeners to be created. If this logical is not defined, the default is 1. Note that the maximum number of Bequeath Listeners is ten (0...9). This script uses one optional parameter that is the listener number. The default is the number 0.

STATUS_BEQLSNR.COM

Query the Bequeath Listener to determine whether it is running and to get some statistical information. This script uses an optional parameter that is the listener number. The default is number 0.

SHUTDOWN_BEQLSNR.COM

Shutdown the Bequeath Listener. This script uses an optional parameter that is the listener number. The default is number 0. Because the Bequeath Listener is the default connection when not using the LISTENER, it should always be running. The LISTENER starts implicitly when INSORACLE is invoked, and it stops when REMORACLE is invoked.

The Bequeath Listener is used during database creation.

Installation

All the installation is done automatically and no specification is needed when doing a new 7.3.3. installation.

Starting up the Bequeath Listener

The Bequeath Listener starts automatically when INSORACLE is invoked (during the creation of a database). Unless you decide to invoke the REMORACLE command, the Bequeath Listener should be up and running all the time.

If the Bequeath Listener is down and you want to start it, execute the command:

BEQLSNR START

The following messages should occur:

Start BEQ listener

%RUN-S-PROC_ID, identification of created process is 5EA00E49

Querying Status of the Bequeath Listener

You can issue a status command to determine whether the Bequeath Listener is up and running.

The command to determine whether the Bequeath Listener is up and running is:

BEQLSNR STATUS

Messages like the following will occur:

BEQLSNR for VMS:  Version 2.3.3.1.1 - Production on 1-AUG-1997 14:38:56.38
Copyright (c) Oracle Corporation 1994, 1997.  All rights reserved.
Started on 1-Aug-1997 14:38:48.38  Pid is 27205F75

Connecting to ORA_BEQ_READ_MBX_1005ap6VMS_0
DEDICATED SERVER current:1  established:1  refused:0

This information contains:

Version number of the Bequeath Listener

Startup time and pid number

Mailbox name that the Bequeath Listener is listening on

Statistic line that contains the current number of connections that are now going through the Bequeath Listener; the number of connections that were totally established; the number of refused connections that didn't complete the client/server connection. Examples of refused connections are when the client made a ctrl-c during a connection or there is a problem creating this client/server connection.

When you have a current connection that uses the Bequeath Listener, messages like the following will occur:

BEQLSNR for VMS: Version 2.3.3.1.1 - Production on 1-AUG-1997 14:38:56.38
Copyright (c) Oracle Corporation 1994, 1997.  All rights reserved.
Started ON 1-AUG-1997 14:38:48.38 Pid is 27205F75

Connection to ORA_BEQ_READ_MBX_1005ap6VMS_0
DEDICATED SERVER current:1  established:1  refused:0

[SVRMGR]SVRMGRL.EXE;14 27205F67 ----->   SRV.EXE;24 27205F76
RGUTHERZ  1-AUG-1997  14:31:42.08  [RON733]  1-AUG-1997  14:38:50.27

This information shows all the pairs of client/server processes that are now connected. You also see the name of client/server images that are now running, their pids, and the login time of these processes. On the left you will also see the client user name. The brackets in the middle show you the SID name. Note that you can see different SIDs, because the Bequeath Listener serves all the instances on the same installation.

Shutting Down the Bequeath Listener

The command is:

BEQLSNR STOP

Note: Generally this option should not be used. The Bequeath Listener shuts down implicitly when REMORACLE is invoked.

Problem Resolution

Writing trace information The Bequeath Listener writes some trace information, but because the output of the detached processes is set to the null device (NL:), normally you will not see it.

To get the trace information from the Bequeath Listener, you should do the following:

1. Stop the Bequeath Listener

2. Edit the STARTUP_BEQLSNR.COM

3. Change the NL: to a file name

4. Restart the Bequeath Listener Changing the quota for a Server Process that is created by the Bequeath Listener To change the quota, modify the file BEQLSNR.COM and remove the comments for the quota parameter that you want to change. Be sure to STOP/START the Bequeath Listener after modifying this file.

Hitting the problem: ORA-12203: TNS:unable to connect to destination If you hit this problem, issue the command BEQLSNR STATUS to determine whether the Bequeath Listener is up and running. If the Bequeath Listener does not respond, use the command BEQLSNR STOP to stop the Bequeath Listener and use the command BEQLSNR START to restart it.

Client hitting the problem: ORA-12203: TNS:unable to connect to destination Choose one of the following solutions:

Change the logical ORA_BEQ_TIMEOUT to something greater than 120 seconds (for example: 300 seconds). Before running the client program, define this logical also in the ORA_NETWORK:BEQLSNR.COM file

Define the logical ORA_BEQ_NUM_OF_LISTENERS to a value between 1 and 10 to increase the capacity when a number of clients are connecting at the same time to the Bequeath Listener.

With this method, you can increase the number of connections that the Bequeath Listeners can handle at one time. Each time that a client requests a connection, it will randomly pick one of the Bequeath Listeners that are running to serve it with the connection request. Note that you do not need to STOP/START the Bequeath Listener after defining this logical name. This logical name determines the number of Bequeath Listeners.

PROTOCOL	The keyword that identifies the specific protocol adapter used; for this protocol, the value is IPC. The value can be entered in either uppercase or lowercase.
KEY	The logical name used to connect to the listener via the Mailbox adapter.

PROTOCOL	Keyword that identifies the specific protocol adapter used; for this protocol, the value is DECNET. The value can be entered in either uppercase or lowercase.
NODE	Name of the remote node to which you want to connect. This node must be included in the list of your system's node names. Use the NCP utility to display these parameters by entering the following command in NCP:

OBJECT	DECnet object name of the listener to which you want to connect on the specified node. The object is created when the listener starts and is deleted when the listener is stopped. The object of an alias used in the TNSNAMES.ORA file must have a corresponding address in the LISTENER.ORA file; it must have the same object, protocol, and node. An object name must be less that 15 characters in length.
	Use upper case when entering object IDs.
QUEUESIZE	Parameter that can be used to enlarge the connection mailbox. This parameter is optional; if it is not specified, the default value of 20 is used, allowing twenty DECnet connections to the listener to be pending. If many simultaneous connections are made to the listener, some connection requests may not be received if the DECnet connection mailbox is too small.

Protocol Service	Supported Version
Digital TCP/IP Services for OpenVMS (UCX)	`4.0`
Cisco MultiNet	`4.0`
Process Software TCPware	`5.1`
Table 3-1 Minimum supported version of TCP/IP products

PROTOCOL	Keyword that identifies the specific protocol adapter used; for this protocol, the value is TCP. The value can be entered in either uppercase or lowercase.
HOST	Host name or IP address.
PORT#	TCP/IP port number of the listener to which you wish to connect on the host specified.
QUEUESIZE	Parameter to increase the queue size. This parameter is optional; if it is not specified, the default value of 20 is used. If simultaneous connections are made to the listener, some connection requests may not be received if the listener socket queue size is too small.