1.0 INTRODUCTION
================

Prior to Oracle 8i, a listener was statically configured (listener.ora)
to
service a given set of SIDs. From 8i, PMON dynamically registers a
database
service with the listener.

Further, if the listener is running on the default TCP port of 1521,
then
there is no need to configure a listener.ora at all.


2.0 USING A DEFAULT LISTENER
============================

A listener.ora file is not required in order to use the default
listener.

The listener is started in the conventional manner:
 $lsnrctl start

This listener will listen on two addresses:
   (ADDRESS=(PROTOCOL=ipc)(KEY=PNPKEY))
   (ADDRESS=(PROTOCOL=tcp)(PORT=1521))

In order to change parameters to non default values (such as enabling
listener tracing), then a listener.ora should be created with the
relevant
parameters specified. The listener then needs to be restarted.

By default, PMON will register the database service with the listener on
port
1521.


3.0 USING A NON DEFAULT LISTENER
================================

When a non-default listener is used, then a listener.ora must be
configured
with the relevant listener address.

For example,

LISTENER =
 (ADDRESS_LIST =
   (ADDRESS = (PROTOCOL=TCP) (HOST=uksn115) (PORT=2500))
 )

This would start a listener on port 2500.

In order for PMON to be able to register the database service(s) with
this
listener, the init.ora parameter LOCAL_LISTENER must be set.

eg,
LOCAL_LISTENER=listener_A

PMON will attempt to resolve LOCAL_LISTENER using some naming method.
For example, this may be resolved in tnsnames.ora, as follows:

listener_A =
  (DESCRIPTION =
    (ADDRESS=(PROTOCOL=TCP)(HOST=uksn155)(PORT=2500))
  )

PMON will search for tnsnames.ora in the following order:
  $HOME/.tnsnames.ora
  $TNS_ADMIN/tnsnames.ora
  /var/opt/oracle/tnsnames.ora or /etc/tnsnames.ora   (depending on
platform)
  $ORACLE_HOME/network/admin/tnsnames.ora


If a tnsnames.ora cannot be found or if LOCAL_LISTENER cannot be
resolved, the
alert.log will show:

     PMON started with pid=2
     Syntax error in listener string 

If LOCAL_LISTENER can be resolved, but there is a syntax error in the
tnsnames.ora specification, the alert log will show:

     PMON started with pid=2
     Syntax error in listener string (DESCRIPTION =)

The instance will start regardless of PMON errors during registration,
unless
MTS is enabled.

If MTS enabled, then both of the above error scenarios will give:

     ORA-00101: invalid specification for system parameter
MTS_DISPATCHERS

in addition to the relevant alert log message. The instance will not
start.

Note that if 'NAMES.DEFAULT_DOMAIN' is set in sqlnet.ora, then the
tnsnames.ora
entry should be of the form .

The domain will be appended to LOCAL_LISTENER if not already specified.

eg,
  init.ora:           LOCAL_LISTENER=listener_A (or
listener_A.uk.oracle.com)
  sqlnet.ora:         NAMES.DEFAULT_DOMAIN=uk.oracle.com
  tnsnames.ora:       listener_A.uk.oracle.com=(...)

The search order for the 'system' sqlnet.ora is:

  $TNS_ADMIN/sqlnet.ora
  $ORACLE_HOME/network/admin/sqlnet.ora

Additionally, the 'local' sqlnet.ora is always read from:

  $HOME/.sqlnet.ora

If this file exists, then any parameters defined here will override the
ones
in the 'system' sqlnet.ora.

Note, /etc or /var/opt/oracle is not searched for the 'system'
sqlnet.ora
unless TNS_ADMIN happens to be set to this directory.


4.0 WHAT INFO IS REGISTERED?
============================

The easiest way to check the information registered by PMON is to enable
level
16 (SUPPORT) listener tracing.


4.1 8.1.5 Registration
----------------------

In 8.1.5, the listener trace shows that the 'register' command is
actually
a CONNECT packet. This is of the form:

 (CONNECT_DATA=
   (COMMAND=service_register)
   ...
   (SERVICE=)
   ...
   (INFO=LOCAL SERVER)
   (DISPLAY=DEDICATED SERVER)
   (GLOBAL_NAME=.)
   ...
   (ENVS='')
   ....
 )


4.2 8.1.6 Registration
----------------------

In 8.1.6, this process has changed slightly. PMON initiates registration
by
sending the following CONNECT packet

  (CONNECT_DATA=
   (COMMAND=service_register_NSGR)
  )

The listener responds with an ACKnowledgement. PMON and the listener
then
exchange DATA packets to complete the registration.


4.3 Compatibility
-----------------

The listener is backwards compatible. Therefore, an 8.1.5 instance can
register with a 8.1.6 listener.

However, it is not possible to register an 8.1.6 instance with an 8.1.5
listener. This is due to the 8.1.5 listener not recognising the
'service_register_NSGR' command.

This can be seen from a listener trace:
 ...
 (CONNECT_DATA=
   (COMMAND=service_register_NSGR)
 )                                <-- extracted from packet dump
 nscon: got NSPTCN packet         <-- a CONNECT packet is rxed
 ...
 nsglfc: The command was not recognized
 ...
 nscon: sending NSPTRF packet     <-- a REFUSE packet is sent


5.0 SPECIFYING MULTIPLE LOCAL_LISTENERS
=======================================

Multiple LOCAL_LISTENERs can be specified in one of two ways in the
init.ora:

a. local_listener=listener_A, listener_B
b. local_listener=listener_A
   local_listener=listener_B

In both cases, v$parameter will show:
local_listener=listener_A, listener_B

PMON will register ONLY with the listener that appears first in the
v$parameter value for local_listener (ie, listener_A in the above).

The correct method is to specify one local_listener in the init.ora, and

to specify multiple listener ADDRESSes in the connect descriptor.

For example,

init.ora:
   local_listener=all_listeners

tnsnames.ora:
   all_listeners.uk.oracle.com=
    (DESCRIPTION =
      (ADDRESS=(PROTOCOL=TCP)(HOST=host1)(PORT=2500))
      (ADDRESS=(PROTOCOL=TCP)(HOST=host1)(PORT=2600))
    )

In non-MTS mode, all listeners must be on the same host as the instance
(unless
pre-spawned servers are used on the remote host).
@However, even in dedicated mode and no pre-spawned servers, PMON still
@registers with listeners on another node. But this does not make any
sense,
@as the remote listener will not be able to fork/exec oracle


6.0 Registration in an MTS Environment
======================================

Service registration is more flexible if the instance is running in MTS
mode. For example,
 - PMON can register services with listeners on more than one node
 - the dispatchers can register with a different listener than dedicated

   services
 - different dispatchers can register with different listeners

This is illustrated by way of the following examples.


6.1 Example1
------------

init.ora on host1:
   local_listener=all_listeners
   mts_dispatchers="(protocol=tcp)"

tnsnames.ora on host1:
   all_listeners.uk.oracle.com=
    (DESCRIPTION =
      (ADDRESS=(PROTOCOL=TCP)(HOST=host1)(PORT=2500))
      (ADDRESS=(PROTOCOL=TCP)(HOST=host1)(PORT=2600))
    )

output of 'lsnrctl services':

  host1, listener on port 2500:
  -----------------------------
     Services Summary...
       V816         has 2 service handler(s)
         DEDICATED SERVER established:0 refused:0
           LOCAL SERVER
         DISPATCHER established:0 refused:0 current:0 max:1022
state:ready
         D000 
         (ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=59155))

  host1, listener on port 2600:
  -----------------------------
   Services Summary...
     V816         has 2 service handler(s)
       DEDICATED SERVER established:0 refused:0
         LOCAL SERVER
       DISPATCHER established:0 refused:0 current:0 max:1022 state:ready

         D000 
         (ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=59155))

In this case, the dispatcher has registered with the listeners specified

by the local_listener parameter.

6.2 Example2
------------

init.ora on host1:

mts_dispatchers="(protocol=tcp)(listener=listener_host2.uk.oracle.com)"
   local_listener=listener_host1.uk.oracle.com

tnsnames.ora on host1:
   listener_host2.uk.oracle.com=
    (DESCRIPTION =
      (ADDRESS=(PROTOCOL=TCP)(HOST=host2)(PORT=2500))
    )
   listener_host1.uk.oracle.com=
    (DESCRIPTION =
      (ADDRESS=(PROTOCOL=TCP)(HOST=host1)(PORT=2500))
    )

output of 'lsnrctl services':

  host1:
  ------
    Services Summary...
       Nov10         has 1 service handler(s)
         DEDICATED SERVER established:0 refused:0
           LOCAL SERVER

  host2:
  ------
     Services Summary...
       V816         has 1 service handler(s)
         DISPATCHER established:0 refused:0 current:0 max:1022
state:ready
           D000 
           (ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=59165))

In this case, the dispatcher explicitly registers with a different
listener
than the one for the dedicated service.

6.3 Example3
------------

init.ora on host1:
   mts_dispatchers="(protocol=tcp)(listener=listenerA.uk.oracle.com)"
   local_listener=all_listeners

tnsnames.ora on host1:
   all_listeners.uk.oracle.com=
    (DESCRIPTION =
      (ADDRESS=(PROTOCOL=TCP)(HOST=host1)(PORT=2500))
      (ADDRESS=(PROTOCOL=TCP)(HOST=host1)(PORT=2600))
    )
   listenerA.uk.oracle.com=
    (DESCRIPTION =
      (ADDRESS=(PROTOCOL=TCP)(HOST=host1)(PORT=2600))
    )


output of 'lsnrctl services':

  host1, listener on port 2500:
  -----------------------------
     Services Summary...
       V816         has 1 service handler(s)
         DEDICATED SERVER established:0 refused:0
           LOCAL SERVER

  host1, listener on port 2600:
  -----------------------------
     Services Summary...
       V816         has 2 service handler(s)
         DEDICATED SERVER established:0 refused:0
           LOCAL SERVER
         DISPATCHER established:0 refused:0 current:0 max:1022
state:ready
           D000 
           (ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=59160))

This illustrates that the 'listener=' part of mts_dispatchers overrides
local_listener when registering dispatchers.
If 'listener=' had not been specified, this example would be the same as
6.1.


7.0 Static Info Overwrite
=========================

If a listener.ora is used, and a SID_DESC entry exists for an instance,
the
data within the SID_DESC section is referred to as 'static information'
for
that instance.

In 8.1.6, all static information in the listener.ora is overwritten when

the instance is dynamically registered with the listener.

Therefore, any environment variables set within the listener.ora will
not
be visible unless the variable is set in the environment used to start
the
instance (and thus inherited by PMON).

This behaviour is different from 8.1.5. In 8.1.5, the existance of a
SID_DESC
section results in the listener NOT registering PMON's (and therefore
the
instances' environment (note that the instance is still registered).

Therefore, in 8.1.5, any environment variables set in the listener.ora
would be
retained even after dynamic registration.

If there is no SID_DESC section, then the listener WILL register PMON's
environment (ie, behaves as 8.1.6).


1