Createtnsnames

Creating a tnsnames.ora file Networking Tips

Creating a tnsnames.ora file

You can create a tnsnames.ora file using nothing more spectacular than Notepad or (if you
are that way inclined, and using a Unix box) vi, pico or any other text editor of your choice.
The point is, tnsnames is just a text file, and any old text editor will do the job.

However (and it’s a big one!), the tnsnames file has a syntax that’s rather tricky at the
best of times, and you’d be much better advised to use the Net8 Configuration Assistant to
do the deed. It will prompt you for various bits of information, and then construct a
functioning tnsnames.ora file for you. Once you’ve got that, any small bits of editing you
might need to do are easy to perform in a text editor.

To run the Configuration Assistant on Windows, just select [Start] [Programs] [Oracle –
Oracle Home name] [Network Administration] [Oracle Net8 Configuration Assistant]. On
Unix, you just type netca from $ORACLE_HOME/bin to launch the same tool (if that
directory is in your PATH, of course, you can run it from anywhere).

Incidentally, for Oracle 9i on Windows, the location of the program changed (just to keep
you on your toes, you understand!). Try: [Start] [Programs] [Oracle – Oracle Home name]
[Configuration and Migration Tools] [Net Configuration Assistant]. It’s the same tool as in
8i when you finally get there!

Finally, note that in 8i there’s another option in Windows called “Net8 Assistant” (in 9i,
it’s called “Net Manager”). I’d advise you not to use this option: it does the same job as
the Net8 Configuration Assistant, but assumes you know what you are doing, and that you
know how to navigate your way to precisely the right bit of the Net8 architecture to do
some configuration work. It’s not Wizard-driven, in other words; and when you’re just
starting out, the hand-holding of the Wizard can be quite helpful. By all means, if you are
already a Net8 Guru, use the more advanced tool –it’s quicker, in some respects- but if you
are already a Guru, I’d question why you’re reading this paper in the first place!

Anyway, let’s assume you’ve fired up the Net8 Configuration Assistant (or its 9i equivalent).
You’ll see something that looks like this:

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


So the first thing you’ll notice about this tool is that it is something of a one-stop shop: you
can use it to create not only tnsnames.ora, but new Listeners (i.e., listener.ora) and new
sqlnet.ora files too.

Since tnsnames.ora is a local naming method, we need the third option from this screen
(“Local Net Service Name configuration”). Select that, and click [Next].

If this is the first time you’ve invoked the tool, your only available option now will be to
“Add”. The other options are available only if you’re using the tool to edit a previously-
created tnsnames.ora. Assuming “Add” is selected, click [Next].



You need to specify whether you are trying to connect to an 8.0 (or 7.0) database, or an 8i
(and above) version. The difference is that in 8i, Oracle introduced the ability for an
Instance to register itself automatically with the Listener. Before that, Instance names
had to be manually configured. So the selection here is really a matter of whether that
extra configuration needs to be prompted for. I’m going to assume that you’re working
with 8i and above (if you’re not, it’s time to upgrade).

The first potentially hazardous screen! You need to specify which Instance you want to
connect to. The screen suggests that you should normally enter the global database name,
which is constructed from the DB_NAME and the DB_DOMAIN parameters of your database’s



init.ora. In my case, that would be “db9.aldeburgh.local” (because my DB_DOMAIN
happens to be set to ‘aldeburgh.local’) but, as you can see, I’ve trimmed that down to just
“db9”, because I want to illustrate what happens when you confuse the global database
name with the friendly alias that you usually get familiar with as the connection identifier.
On page 6, you’ll see what happens when you don’t specify the right service name as a
result of this (quite common) error.

Incidentally, it’s quite easy to determine what name should actually go here. If you go to
the server, and (at a command prompt) type lsnrctl services, you’ll see something that
looks like this:

C:Documents and SettingsAdministrator>lsnrctl services

LSNRCTL for 32-bit Windows: Version 9.0.1.1.1 - Production on 17-MAR-2002 08:45:56

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

Connecting to (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=mozart)(PORT=1521)))
Services Summary...
Service "db9.aldeburgh.local" has 3 instance(s).
Instance "db9", status UNKNOWN, has 1 handler(s) for this service...
Handler(s):
"DEDICATED" established:0 refused:0
LOCAL SERVER
Instance "db9", status READY, has 1 handler(s) for this service...
Handler(s):
"DEDICATED" established:0 refused:0 state:ready
LOCAL SERVER
Instance "db9", status READY, has 1 handler(s) for this service...
Handler(s):
"DEDICATED" established:1 refused:0 state:ready
LOCAL SERVER
The command completed successfully

What the Listener determines the service name to be (which I’ve highlighted in bold) is
what should go into this screen as the service name. When you’ve entered a name, press
[Next].



Here we need to specify which networking protocol to use for connections to the just-
specified Instance. You’ve a choice, as you can see… but what choices here depends
entirely what networking protocol adapters have been installed beforehand. See my paper
“What does "Protocol Adapter Not Found" mean?” for details about these. I suspect that
the majority of Users are going to be using TCP/IP for their connections, and that’s the one
I’ve selected here. One interesting note: in 9i, IPX/SPX is no longer a supported network
protocol. Choose your protocol, and click [Next].

Now you have to know a little about how your Listener has been configured –in other words,
you can’t really create a tnsnames.ora until after you’ve configured your Listener. Two
pieces of information are required: what box does the Listener reside on, and what port is
it listening on.

In this example, I’ve used a machine name for the ‘Host Name’ field. That rather assumes
that I have an external mechanism for resolving that name, such as an lmhosts file, or
some sort of Directory Service. Actually, I use Windows 2000 Active Directory, so this
entry makes sense. In the absence of those sorts of mechanisms, typing in the IP address
of the machine directly would have been appropriate.

The default port for any Listener is 1521 (from dim and distant memory, it used to be 1526
on Oracle 7). Automatic instance registration is a doddle when the default port is used as
part of Listener configuration, but gets rather more complicated if any other port is
selected (see my paper “What is 'automatic instance registration', and is it useful?” for
details). Unless there are particular constraints on your freedom of action, therefore, I’d
always recommend using the default port. In which case, you can now just click [Next],
because the wizard by default selects for that port. Of course, if you’ve previously



configured the Listener to listen on a non-default port, you’ll need to click the ‘Use
another port number” radio button, type in the port number, and then click [Next].

And that’s it really. All you’ve done is to specify which Instance to connect to, what
protocol to use for connections to that Instance, and given the location details for the
Listener that is handling connection requests for that Instance. The rest of the wizard is
merely designed to make sure that all the information you’ve provided is accurate.

I strongly suggest you select the ‘Yes, perform a test’ option, and then click [Next]. You’ll
get one of two sorts of responses. The bad sort will look like something like this:



In this particular case, there’s obviously a problem with the service name I supplied 4
screens ago. Usually, that’s because the supplied service name doesn’t match the global
database name under which the Instance has registered itself with the Listener. If that’s
your problem, just click [Back] as many times as it takes to get to the relevant earlier
screen, and correct your problem. In my case, going back and changing the service name
from “db9” to “db9.aldeburgh.local” (which, you’ll remember, is what the Listener knows
my service name as –see the lsnrctl output on page 4), and then clicking [Next] to get back
to the testing screen yields this response, second time around:

This still doesn’t look too good, but if you read the error message carefully, it’s clear that
in fact connectivity to the Instance has been established. The problem this time is that
the test uses (by default) the username “SCOTT” and the password “TIGER”. If your
database doesn’t have a user of that name, or if you’ve changed Scott’s password, then
the “invalid username/password; logon denied” error message is rather expected. The
point, though, is that the wizard must have been able to contact that database to find out
that no such User account exists. All we really need to do to make sure is to get the
wizard to try connecting as a User who we can guarantee exists in the database –and a
prime candidate for that would be SYSTEM, password MANAGER. To change the test’s
logon credentials, just click the [Change Login] button:



Supply the new username and password (as I’ve done here), and then click [OK].
Immediately you do that, the wizard makes a fresh attempt to logon to the database, and
you should see a screen like this:

Once you know that the logon works, you can click [Next]. You’ll then see this screen:

Here, you supply a “Net Service Name”. This has nothing necessarily to do with the
‘Service Name’ we supplied back on Page 3, but can be any friendly name you want to use
to connect to the database. The fact that your database is technically known by the
Listener as, for example, “db9.aldeburgh.local” doesn’t stop you from naming it here as



something rather more intuitive, such as “SALES”, or “ACCOUNTS” or “CUSTOMERS”. The
name you supply here is what Users will supply when making connections, so it helps if it’s
something meaningful and obvious. The screen will usually supply a default name,
extracted from the full service name entered earlier, but feel free to over-type the
suggestion with anything that makes sense to you.

Finally, click [Next], and you’ll see this screen:

If you want to go through the entire process to establish other connections to the same or
different databases, select [Yes], and click [Next]. Otherwise, make sure [No] is selected,
click [Next], and you’ll get a confirmation message that “Net service name configuration is
complete”. One more click of the [Next] button, and you’ll be back to the first screen of
the wizard. From there, you can just click [Finish] –whereupon the wizard will close.

At this point, I’d recommend making sure that connectivity really has been established.
The easiest way to do that would be to fire up SQL*Plus at the command line, and see what
happens when you try and establish a connection. Here’s what happens when I try that:

C:Documents and Settingshowardjr>sqlplus /nolog

SQL*Plus: Release 9.0.1.0.1 - Production on Sun Mar 17 09:30:37 2002

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

SQL> connect system/manager@sales
ERROR:
ORA-12154: TNS:could not resolve service name



Clearly all is not well with this connection, even though the wizard seemed happy enough.
So at this point, we need to look at the tnsnames.ora file that the wizard created for us,
and see what on Earth is going on.

All Oracle networking configuration files are, by default, stored in the
ORACLE_HOME/network/admin directory on Unix, and ORACLE_HOMEnetworkadmin directory on Windows

(and obviously, “ORACLE_HOME” there is an environment variable that points to whatever
parent directory you’ve already established as the home for your database files). You can
change the default location, incidentally, by setting yet another environment variable
called TNS_ADMIN. So, this command means I can move my configuration files to the root
of the C: drive: set TNS_ADMIN=C: (on Unix, you use the “export” command, rather
than “set”, but otherwise it’s much the same).

So, if we go to the networkadmin directory (or wherever TNS_ADMIN is pointing), we
should find our tnsnames.ora file, which we can open in the text editor of our choice.
Mine looks like this:

# TNSNAMES.ORA Network Configuration File:
F:oracleora90networkadmintnsnames.ora
# Generated by Oracle configuration tools.

SALES.ALDEBURGH.LOCAL =
(DESCRIPTION =
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = TCP)(HOST = mozart)(PORT = 1521))
)
(CONNECT_DATA =
(SERVICE_NAME = db9.aldeburgh.local)
)
)

Here, the connection problem I had before is perfectly obvious: I was trying to connect to
something called “SALES”, and the tnsnames.ora only knows something about an Instance
called “SALES.ALDEBURGH.LOCAL”. Hence the “could not resolve service name” error
message I was receiving earlier. It means that the name you supplied after the “@”
symbol doesn’t match any of the tns aliases (that is, the friendly names used to identify a
database) that exist in the tnsnames.ora file.

If I go back to SQL*Plus armed with this knowledge, and try again using the correct alias, I
get this:

SQL> connect system/manager@sales.aldeburgh.local
Connected.

Now this is all very well, but it’s not what we wanted. We wanted our Users to be able to
type ‘@SALES’ and have the connection work. Having to type all the rest of the long-
winded domain name is, frankly, a pain in the neck.



There are two approaches to tidying this up. We can either edit the tnsnames.ora file
directly, so that the tns alias simply reads “SALES”. Or we can get Oracle to automatically
append the domain name (in my case, ‘aldeburgh.local’) to any alias the User supplies,
every time they supply it.

For the first approach, you need simply edit the tnsnames.ora so that it reads like this:

# TNSNAMES.ORA Network Configuration File:
F:oracleora90networkadmintnsnames.ora

SALES =
(DESCRIPTION =
(ADDRESS_LIST =
)
(CONNECT_DATA =
)
)

Notice it’s just that first line that gets altered –the details of the SERVICE_NAME, for
example, remain untouched. Save that, and then back in SQL*Plus, we can try again:

SQL> connect system/manager@sales
Connected.

So that’s nice and easy.

The more ‘technically correct’ approach is to configure a sqlnet.ora file that reads like this:

# SQLNET.ORA Network Configuration File: F:oracleora90networkadminsqlnet.ora

NAMES.DEFAULT_DOMAIN = aldeburgh.local
NAMES.DIRECTORY_PATH= (TNSNAMES)

The first line of this file tells Oracle to always assume that references to “SALES” on its
own should actually be interpreted as referring to SALES.aldeburgh.local. In other words,
Oracle will automatically append the specified domain name on to the end of a connection
alias, if it is needed.

So if our tnsnames.ora file still reads:

SALES.ALDEBURGH.LOCAL =
(DESCRIPTION =

…etc, then with a sqlnet.ora looking like the one I’ve just shown you sitting in the
ORACLE_HOMEnetworkadmin directory, we can go back to SQL*Plus and do this:



SQL> connect system/manager@SALES
Connected.

So now our Users can connect with the short form alias, even though the tnsnames.ora still
contains the long form alias. On the other hand, if you try this:

SQL> connect system/manager@sales.aldeburgh.local
Connected.

…then it’s clear that Oracle is smart enough to notice that you’ve been good enough to
supply the domain name yourself, and it won’t append the default domain name.

Just to summarise that:

SALES = SALES.ALDEBURGH.LOCAL =
(DESCRIPTION = (DESCRIPTION =
(ADDRESS_LIST = (ADDRESS_LIST =
(ADDRESS = (PROTOCOL = (ADDRESS = (PROTOCOL = TCP)(HOST
If your tnsnames TCP)(HOST = mozart)(PORT = 1521)) = mozart)(PORT = 1521))
) )
reads like this: (CONNECT_DATA = (CONNECT_DATA =
(SERVICE_NAME = (SERVICE_NAME =
db9.aldeburgh.local) db9.aldeburgh.local)
) )
) )
And your
NAMES.DEFAULT_DOMAIN = aldeburgh.local
sqlnet.ora reads Empty, or simply doesn’t exist
NAMES.DIRECTORY_PATH= (TNSNAMES)
like this:
Connect system/manager@sales
Then this
AND
connection will Connect system/manager@sales
work: Connect
system/manager@sales.aldeburgh.local
Connect
But this one won’t: Nothing: everything works!
system/manager@sales.aldeburgh.local

Because using the sqlnet.ora file to supply a default domain gives you the flexibility of
being able to use both connection strings, the Oracle recommended approach is to use that
method to sort out the connection problem. (Incidentally, as my paper “What does
sqlnet.ora do for me?” explains, the sqlnet.ora has many more uses than just this one, so
there are other reasons for this being the appropriate solution).

On the other hand, I’ll confess that, because…

• I run my network with TCP/IP (the default protocol)
• my Listener always gets given a default name and a default port
• I use local naming methods (that is, a tnsnames.ora)
• I don’t need Windows account authentication to allow access to the database

…I actually have no need for a sqlnet.ora, and therefore rarely bother to create one. So I
would myself resort to simply making a direct edit of the tnsnames.ora file to get a quick
fix to the problem.



The point I think I want to make in conclusion is that the Net Configuration wizard is only
the start of the exercise. It makes the creation of a tnsnames.ora file very easy, but it
may end up introducing certain elements into the file which continue to cause you (or your
Users grief). Remembering that at the end of the day it’s only a text file, you can always
invoke any old text editor to knock it into a shape that suits you.

Just remember that, when you do choose to edit the file directly, you need to be careful
not to disturb the formal syntax or layout too much.

For example, this tnsnames.ora won’t work:

SALES =
(DESCRIPTION =
(ADDRESS_LIST =
)
(CONNECT_DATA =
)
)

Here, I’ve stripped out all the careful indenting that the wizard supplied (and that’s the
only change I’ve made), and when I try to connect, I get this:

SQL> connect system/manager@SALES
ERROR:
ORA-12154: TNS:could not resolve service name

It’s really not so much that it can’t resolve the service name (after all, the tns alias is
“SALES”, and that’s what I’ve supplied in the connect string) as that it can’t parse the
tnsnames.ora file in the first place.

This tnsnames.ora, however, will work:

SALES =
(DESCRIPTION =
(ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = mozart)(PORT = 1521)))
(CONNECT_DATA = (SERVICE_NAME = db9.aldeburgh.local))
)

Even this one works:
SALES =
(DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = mozart)(PORT = 1521)))
(CONNECT_DATA = (SERVICE_NAME = db9.aldeburgh.local)))

Here, I’ve retained the indentations of the lines, but I’ve combined several lines into one.
Just to emphasise how sensitive the thing can be, I’ll try that again, using exactly the same
layout as before, but with just a couple of “minor” changes:



SALES =

… once again, the only difference here is that there are no indents to the lines.

And one last test, just to show you how confusing and frustrating this can be:

SALES =

That last one works, though you’ll be hard-pressed to spot the difference between it and
the earlier one that didn’t. In fact it is the existence of a single space before the
“(CONNECT_DATA…” line!

The message is simple, therefore: Spaces and indentation are significant (that’s why
using the wizard in the first place, which gets all the layout correct, is strongly
recommended).


Createtnsnames

More Related Content

Similar to Createtnsnames

More from oracle documents

Createtnsnames