createtnsnames

Creating a tnsnames.ora file Networking Tips

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

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:



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 Settings\Administrator>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 Settings\howardjr>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_HOME\network\admin 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 \network\admin 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:\oracle\ora90\network\admin\tnsnames.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/[email protected] 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:\oracle\ora90\network\admin\tnsnames.ora # Generated by Oracle configuration tools. SALES = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = mozart)(PORT = 1521)) ) (CONNECT_DATA = (SERVICE_NAME = db9.aldeburgh.local) ) ) 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:\oracle\ora90\network\admin\sqlnet.ora # Generated by Oracle configuration tools. 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_HOME\network\admin 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/[email protected] 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:

If your tnsnames reads like this:

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

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

And your sqlnet.ora reads like this:

Empty, or simply doesn’t exist NAMES.DEFAULT_DOMAIN = aldeburgh.local NAMES.DIRECTORY_PATH= (TNSNAMES)

Then this connection will work:

Connect system/manager@sales

Connect system/manager@sales AND Connect system/[email protected]

But this one won’t: Connect system/[email protected]

Nothing: everything works!

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 = (ADDRESS = (PROTOCOL = TCP)(HOST = mozart)(PORT = 1521)) ) (CONNECT_DATA = (SERVICE_NAME = db9.aldeburgh.local) ) ) 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 = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = mozart)(PORT = 1521))) (CONNECT_DATA = (SERVICE_NAME = db9.aldeburgh.local)))

� 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 = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = mozart)(PORT = 1521))) (CONNECT_DATA = (SERVICE_NAME = db9.aldeburgh.local)))

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

Documents

net8 assistant

service db9

oracle corporation

text file

ready local serverinstance

net8 guru

net8 architecture

right service