Createlistener

How to create a Listener Networking Tips

How to create a Listener?

The process of creating a Listener is really nothing more than knocking together a passable
listener.ora file, and then using the LSNRCTL utility to start the thing. In Windows, this
last step will cause a new service to be created (which is then visible in the Control Panel
Services applet). On Unix, all that happens is that a new process is spawned, which then
carries out the functions of the Listener.

So we start with the need for a listener.ora file. What’s the best way of creating that?
Well, it’s just a text file, so you could open vi or notepad and start typing. But there’s a
lot of significant formatting and some crazy syntax involved, so it’s better to use the
Oracle-supplied Net8 Configuration Assistant to do the job (for Oracle 9i, that utility got
renamed as simply the “Net Assistant”, but it’s essentially the same tool).

To launch that tool on Windows, you click [Start][Programs][Oracle - <Oracle Home>]
[Network Administration][Net8 Configuration Assistant]. (Note that for 9i, the location
changed: [Start][Programs][Oracle - <Oracle Home>][Configuration and Migration
Tools][Net Configuration Assistant].

For Unix, you just type nwca at the command prompt, though frequently many people use
the Configuration Assistant on Windows, and then ftp the resulting configuration across to
the Unix server.

When you start the Assistant, you’ll see this screen:

Copyright © Howard Rogers 2002 3/24/2002 Page 1 of 14


Obviously, the option we need is the top one, which is already selected. So just click
[Next]. That will bring up a screen like this:

There are four options available here, but only the “Add” one will be available if this is the
first Listener to be created on the Server. If there’s an existing Listener, the other three
options will be available, giving you the ability to change its properties, its name, or to get
rid of it altogether. Since we’re creating a new Listener, make sure “Add” is selected, and
click [Next]. The screen changes to this:



The first thing you have to do is give your Listener a name. The default name, and the one
offered as a default, is the strikingly unoriginal “Listener”. A Server can have several
Listeners running on it simultaneously, but each must be uniquely named. So if there’s
already one with this default name, you’ll have to change it here (simply highlight the
suggested name, and over-type it). However, if there is no chance of the default name
conflicting with an existing Listener, I’d recommend you accept the default, however
unoriginal it is. The reason for that is simple: being the default, Oracle relies on its
existamce for such important things as automatic Instance registration (the ability of an
Instance to automatically tell the Listener that it exists). Use a non-default Listener name,
and you’ll be signing up to having to perform additional configuration of the init.ora for all
Instances that this Listener is going to service.

Having chosen a name (or if you like the suggested one), click [Next]. The next screen will
then appear:

Here, you have to state which networking protocols the new Listener will be listening on.
A single Listener can listen on many protocols, so you don’t need one Listener per protocol.
The available protocols are shown in the left-hand pane. The selected ones are on the
right. TCP/IP is the default protocol, and so it should already be in the right-hand pane.
To add others, click on an entry on the left, and then use the top “>” button to transfer it
across to the right. Reverse the process to de-select a protocol. You can then use the up
and down buttons on the right to prioritise the selected protocols if there are more than
one of them. Prioritising protocols like this only makes a difference to the formatting of
the listener.ora text file, and has no effect on the subsequent performance of the Listener.



Incidentally, the list of available protocols will vary from machine to machine, depending
on what Oracle networking protocol adapters you selected to install when installing Oracle
in the first place.

When the correct protocols are displayed in the right-hand pane, click [Next]. The next
screen will then appear:

Here, you select the port that the Listener will monitor to detect connection requests to a
database. A single Listener can only listen on one port, however many databases it’s
servicing connection requests for. The default port for standard TCP/IP connections is
1521 (it used to be 1526 in Oracle 7). This is a good one to accept because, again, if you
elect to listen on a non-default port, Automatic Instance Registration won’t work without
some extra configuration of each database’s init.ora.

This happens to be the screen to configure standard TCP/IP connections. If you’ve
configured other protocols on the previous screen, you’ll need to supply the appropriate
information those other protocols need (for example, Named Pipes requires you to supply a
pipe name; IPC requires a Key Value).

If you selected the TCPS protocol on the previous screen, which is a secured TCP/IP
protocol, the default port number suggested will be 2484. That can again be accepted or
changed by supplying your own port number.

Finally, if you’ve selected multiple protocols on the previous screen, the relevant
configuration screens (such as this one for TCP) will display one after the other, in the
order in which you prioritised the protocols when selecting them.



So, having configured how the Listener should interact with your networking protocol(s),
click [Next], and the following screen should appear:

Assuming you only want to configure one Listener at the present time, you’d accept the
already-highlighted ‘No’ option, and just press [Next]. If you choose [Yes], you’ll go back
to the beginning.

If you answered ‘No’, clicking [Next] will bring up a confirmation message that Listener
Configuration is complete. One more click of the [Next] option takes you back to the first
screen we saw, where you can click [Finish], at which point the wizard will close.

On Windows, by the time you get the ‘configuration complete’ confirmation message,
Oracle will have created and started the relevant service for you. On Unix, the
Listener process will be started automatically, but obviously no service will have
been created, since no such concept exists on Unix.

The fact that the Listener is created and started automatically for you on completion of
the Assistant wizard can be a problem, particularly if you’ve used the Windows version
intending to ftp the resulting listener.ora to your Unix server, or if you’ve used the wizard
on a Windows client intending to transfer it later to a Windows server.

Expect dire errors to be raised when a listener.ora referencing hostname “Britten”, for
example, is transferred to an Oracle server actually called “Mozart” unchanged. Also, be
prepared to invest in a tool that can remove services created ‘inadvertently’ like this on a
Windows machine. Personally, I use Service+ (downloadable at www.activeplus.com), but
the Windows Resource Kit provides a command-line utility that does the same thing for
free.



However, this raises an important point: if you are going to make further configuration
changes to the listener.ora, you need to stop the Listener process or service which has
been automatically created for you. On Windows, this is most easily accomplished by
finding the Control Panel Services applet (often found in Administrative Tools), highlighting
the relevant service, and then using the menu options to stop it. On Unix, you need to
find a command line prompt and type: lsnrctl stop listener_name. If you earlier
opted to use the default listener name, LISTENER, then you can leave off the ‘listener
name’ part of that syntax.

Further Configuration

You will probably want to check what the Wizard has created for you, and maybe make
some alterations to it. In fact, the Wizard creates a text file called listener.ora in the
ORACLE_HOME/network/admin directory (it’s the same directory for Windows, for
versions 8i and 9i, except that the slashes go the other way around!). Bear in mind that
any alterations you make to this file have not the slightest effect on a Listener that is
already running. You’ll need to stop and start the Listener before it becomes aware of
configuration changes in the listener.ora file.

You should open that file, and see what it looks like. In my case, I get this:

LISTENER =
(DESCRIPTION_LIST =
(DESCRIPTION =
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = TCP)(HOST = britten)(PORT = 1521))
)
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = IPC)(KEY = EXTPROC0))
)
)
)
SID_LIST_LISTENER =
(SID_LIST =
(SID_DESC =
(SID_NAME = PLSExtProc)
(ORACLE_HOME = F:oracleora90)
(PROGRAM = extproc)
)
)

Now, although I only selected for TCP protocol, the Wizard has arranged things so that I
automatically get an IPC protocol to handle calls to external procedures (which is what the
bit under the SID_LIST_LISTENER heading is all about). Whether you get the same result,
or something else, depends very much on the specific configuration of Oracle that you’ve
installed.



You may find, for example, that if a database has already been created on the machine
that you ran the networking wizard on, it will have automatically discovered the existence
of that database, and added a reference to that in the SID_LIST_LISTENER bit of the file,
too.

Feel free to edit this text file if it’s not what you want: but bear in mind that the
indentation and formatting created by the wizard is not irrelevant, or there just to make
things look good. Go overboard in your re-formatting and you might have trouble actually
starting the Listener.

In my case, I don’t want external procedures to be called. So whilst I don’t strictly need
to remove references to it, there’s no harm in doing so either. With a bit of judicious
editing, I’m left with a listener.ora that looks like this:

LISTENER =
(DESCRIPTION_LIST =
(DESCRIPTION =
(ADDRESS_LIST =
)
)
)

You will notice that nowhere in this newly-revised file does it state precisely on behalf of
which databases the Listener should be listening. That’s significant, and it’s an entirely 8i
and above feature. Databases of those versions are able to register themselves with the
Listener, so the Listener doesn’t need to be explicitly told about them ahead of time in
the listener.ora. But databases earlier than 8i cannot register themselves automatically,
and the listener.ora needs to reference those databases explicitly.

Let’s assume I wanted my new Listener to listen out for connection requests to an Oracle
8.0.6 database called HR. How would I add that requirement to the listener.ora? Well,
again, you could just edit the file, but it’s easier if you use the Net8 Assistant (renamed
the Net Manager in 9i). Don’t confuse that with the Net8 Configuration Assistant, by the
way. The latter is a wizard-based way of creating the relevant networking configuration
files. The former is a tool to manage things in a way that assumes you know what it is that
you are doing.

Let’s fire up the Net8 Assistant, then, to add in this reference to an Oracle 8 database. In
Windows, click [Start][Programs][Oracle – <Oracle Home>][Network Administration][Net8
Assistant]. (In 9i, it’s [Start][Programs][Oracle – <Oracle Home>][Configuration and
Migration Tools][Net Manager]). Here’s the first screen:



Open the “Local” branch of the tree structure in the left-hand pane, and then the
“Listeners” branch within that, and you’ll see this:

The Listener you configured using the Wizard will be displayed in the tree structure. Click
on that entry, and the right-hand pane will display this:



This is the “Listening Locations” page. It just describes what machine the Listener is going
to run on, what port it will use, and what protocol is going to be used to contact it. If you
look carefully, you’ll see that it corresponds precisely with the edited listener.ora shown
above.

But remember what we wanted to do: add in a reference to an 8.0 database called “HR”,
so that this Listener, when finally its gets to run, will handle the connection requests for
that database. Here’s what we do. Go to the “Listening Locations” label, and click the
little down-arrow symbol on its right. From the menu that is then displayed, select the
“Database Services” option. The left-hand pane will then change to display… pretty well
nothing.

That’s the point, of course. At the moment, we haven’t configured any databases to be
listened for, so there are no “database services” to display. But that’s all about to change.

Click the “Add Database” button at the bottom of the pane. The screen will change to
show the following:



You need to supply just three pieces of information here: the global database name, that
database’s Oracle Home, and the SID by which it is identified. I’ve filled in this screen
shot using the example of a database called “HR”. However, you will probably find that
the screen is initially filled in with a whole bunch of stuff referring to a database called
“ORCL” (which is the default name of the starter database you tend to get when you
install Oracle in the first place). Just overtype that information with your own details, as
I’ve done here.

If you need to specify another non-8i or non-9i database, click [Add Database] again, and
keep going. If you make a mistake, select the appropriate tab containing the erroneous
database details, and click [Remove Database].

When everything is completed to your satisfaction, you need to make sure that the
changes you’ve made in this tool are actually written to the listener.ora configuration file.
So click [File] [Save Network Configuration].

Then click [File][Exit]. For some utterly bizarre reason, you’ll be asked to save your
configuration changes one more time, just in case. Click the [Save] option when prompted,
and the tool will finally close.

If you now open up the listener.ora text file, you’ll see something like this:

LISTENER =
(DESCRIPTION =
)



SID_LIST_LISTENER =
(SID_LIST =
(SID_DESC =
(GLOBAL_DBNAME = HR.aldeburgh.local)
(ORACLE_HOME = d:oracleora806)
(SID_NAME = HR)
)
)

So, the configuration of a non-8i or non-9i version of the database results in the appending
of a SID_LIST_LISTENER section to the file (which it had originally, of course, with the bits
about allowing external procedure calls).

This is an important point. Anything that is listed within a SID_LIST_LISTENER part of a
listener.ora is said to be statically configured. The configuration information, as you can
see, is fairly minimal (we need to know the ORACLE_HOME to make sure that the right
version of the executables are called, if needed. The SID is needed so we know what to
connect to in the first place). But it must be explicitly configured, like this, for any
version of the database prior to 8i.

Databases of versions 8i or higher can perform dynamic configuration –that is, they can
inform the Listener, on startup, of their own existence, and they do not therefore need to
be specified in the listener.ora at all.

Even in 8i or higher databases, however, certain non-core-database services have to be
statically configured. Calls to external procedures have to be, for example, which is why
the configuration wizard automatically put those lines into the original version of my file.
Heterogeneous Services (basically, gateways to non-Oracle databases) must also be
statically configured, even with 8i or 9i databases.

Starting the Listener

With the listener.ora configured one way or another, it’s time to actually start the Listener.
If you ran the configuration wizard described earlier on the Server itself, then the service
has probably already been started for you, as I mentioned on page 5. Quite often,
however, you may run the configuration wizard on your local PC, and then transport the
resulting listener.ora over to the server for later running.

If that’s what you’ve done, you’ll have to start the Listener yourself, using good old
manual methods.

To do this, get yourself to a command line prompt on the server that hosts the database,
and type

lsnrctl start listener_name



If you accepted the default name earlier (“LISTENER”), then you don’t need to specify the
listener name part of this command. If you chose to name your Listener something exotic,
such as FredandGinger, then you must explicitly name it here, otherwise it won’t work.

You’ll see something like the following appear on your screen:

C:Documents and SettingsAdministrator>LSNRCTL start listenerabc

LSNRCTL for 32-bit Windows: Version 9.0.1.1.1 - Production on 24-MAR-2002 15:54:37

Copyright (c) 1991, 2001, Oracle Corporation. All rights reserved.

Starting tnslsnr: please wait...

Failed to open service <OracleOraHome91TNSListenerlistenerabc>, error 1060.
TNSLSNR for 32-bit Windows: Version 9.0.1.1.1 - Production
System parameter file is d:oracleora91networkadminlistener.ora
Log messages written to d:oracleora91networkloglistenerabc.log
Listening on:
(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=mozart.aldeburgh.local)(PORT=1521)))

Connecting to (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=mozart)(PORT=1521)))
STATUS of the LISTENER
------------------------
Alias listenerabc
Version TNSLSNR for 32-bit Windows: Version 9.0.1.1.1 -
Production
Start Date 24-MAR-2002 15:54:41
Uptime 0 days 0 hr. 0 min. 2 sec
Trace Level off
Security OFF
SNMP OFF
Listener Parameter File d:oracleora91networkadminlistener.ora
Listener Log File d:oracleora91networkloglistenerabc.log
Listening Endpoints Summary...
The listener supports no services
The command completed successfully

In this example, I had to specify a Listener name on the command line, because it was
called ‘listenerabc’, and not the plain old default ‘listener’. The operating system reacted
to the request to start my Listener with a quite nasty-looking error:


That’s actually perfectly normal (for Windows, the first time). It just means that the O/S
has discovered that the service for the Listener doesn’t exist –which prompts it to create
the service for you. On Unix, there should be no such messages.

To be absolutely sure the thing is working correctly, try to stop the Listener and then
immediately re-start it (I’ve highlighted the relevant commands):



C:Documents and SettingsAdministrator>lsnrctl stop listenerabc








Listening on:

STATUS of the LISTENER
------------------------
Alias listenerabc
Version TNSLSNR for 32-bit Windows: Version 9.0.1.1.1 -
Production
Start Date 24-MAR-2002 16:02:59
Uptime 0 days 0 hr. 0 min. 2 sec
Trace Level off
Security OFF
SNMP OFF
Listener Parameter File d:oracleora91networkadminlistener.ora
Listener Log File d:oracleora91networkloglistenerabc.log
Listening Endpoints Summary...
The listener supports no services

This time, you’ll notice no unpleasant messages at all. And so now you know the Listener
can stop and start at will, you’ve successfully created and configured a Listener.

Other Issues

If you use the Configuration wizard on one machine intending to transfer the resulting
listener.ora to another one later on, you must edit the listener.ora by hand before
attempting to start the Listener. For example, my earlier example of using the wizard was
done on my client PC, called ‘Britten’, That’s why the listener.ora contained these lines:

(ADDRESS_LIST =
)



Unfortunately, my server hosting Oracle is actually called “Mozart”. Here’s what you can
expect if you ship the listener.ora over to the real server without further modification, and
try and start the Listener:





Error listening on: (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=britten)(PORT=1521)))
TNS-12545: Connect failed because target host or object does not exist
TNS-12560: TNS:protocol adapter error
TNS-00515: Connect failed because target host or object does not exist
32-bit Windows Error: 49: Unknown error

Listener failed to start. See the error message(s) above...

I’ve highlighted the crucial error message, which is easy to miss because of the
overwhelming nature of the complete error stack. Incidentally, on a Windows machine,
even though the Listener couldn’t actually start because of the hostname issue,
nevertheless, the Service is created for you.

Here’s another error situation: if you create a Listener (called in this example ‘listenerabc’)
whose name matches one that has already been created and started, expect something
like this:





Service OracleOraHome91TNSListenerlistenerabc already running.
TNS-12536: TNS:operation would block
TNS-12560: TNS:protocol adapter error
TNS-00506: Operation would block
32-bit Windows Error: 997: Unknown error

In short, pay attention to the host’s name as recorded in the listener.ora, as well as the
Listener Name itself. The former must be accurate, the latter must be unique.


Createlistener

More Related Content

What's hot

Viewers also liked

Similar to Createlistener

More from oracle documents

Createlistener