3.4 Defining Net Service Names If you're using local naming, the next step after configuring your Net8 Profile is to define some net service names. When local naming is used, net service names are defined in a text file named tnsnames.ora . If you are using Oracle Names, host naming, or an external naming service, skip this section. None of those name resolution methods make use of the tnsnames.ora file. You'll find the tnsnames.ora file in the same directory as your sqlnet.ora file. This is usually your $ORACLE_HOME/network /admin directory. On some Unix systems, a different directory may be used. In addition, the TNS_ADMIN environment variable (or registry setting) can be used to override the default location of Net8 configuration files.  | If you are running multiple releases of Oracle client software on one machine, you can use the TNS_ADMIN environment variable to point all those releases to one set of Net8 configuration files. See Appendix E, for details on doing this. | | You can edit the tnsnames.ora file by hand using a text editor, or you can use one of Oracle's "assistants" to do the job for you. The syntax for a tnsnames.ora entry consists of a net service name followed by a description of how to connect to that service. The description is enclosed in parentheses, and elements in the description are also enclosed in parentheses. Some elements are lists that are further enclosed in parentheses. You can have nested lists, also enclosed in parentheses. There are enough parentheses in the syntax to drive most people straight to their optometrist. Here's a typical net service name definition. This is for a service that connects you to an Oracle database over a TCP/IP connection: HERMAN.GENNICK.ORG = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP) (HOST = jonathan.gennick.org) (PORT = 1521)) ) (CONNECT_DATA = (SERVICE_NAME = herman.gennick.org) ) ) There are two problems you run into when editing a tnsnames.ora file by hand. One is that you probably won't remember the correct syntax off the top of your head. The other is that it's very easy to either leave off a parenthesis or improperly nest the elements in a definition. To make life easier, and probably to reduce calls for support as well, Oracle has come up with a few automated assistants to do the job for you. Both the Net8 Assistant and Net8 Easy Config use a GUI interface to walk you through the process of defining a net service name, and at the same time ensure that the correct syntax is written to the file. In this chapter, we discuss the syntax used for net service name definitions first, before going into the use of any of the GUI tools. Once you understand the elements that make up a net service name definition, you won't have any difficulty using the GUI tools. 3.4.1 Advanced Connection Options The net service name definitions that you see in this chapter are basic. They allow you to define a net service name that will connect you to a database, but they don't take advantage of any of Net8's many advanced features. In addition to simply connecting your client to a database, Net8 supports the following: Where these features are used, you'll see net service name definitions that include multiple addresses, multiple address lists, and multiple descriptions. Chapter 9, talks about the use of Net8's Connection Manager. Other advanced features, such as failover and client load balancing, are described in Chapter 8. 3.4.2 Syntax for TNSNAMES Entries The general syntax for a net service name is easiest to explain without resorting to a formal syntax diagram. See Appendix B, if you want to see a formal diagram. A relatively simple net service name definition will look like this: net_service_name = (DESCRIPTION = (ADDRESS = ( address_data )) (CONNECT_DATA = (SERVICE_NAME = database_service_name ) (INSTANCE_NAME = sid ) ) ) The address data is protocol-specific . The next few sections will show you how to define an address using the different protocols that are available. 3.4.2.1 Connect data options There are two ways to identify the database, or instance, to which you want to connect when you use a net service name. You can identify the instance by specifying its system identifier (SID), or you can identify a database by specifying its service name. Prior to release 8.1, you always had to connect to a database through an instance, and you had to use the SID keyword to specify the instance name. For example: (CONNECT_DATA = (SID = herman) ) Net8 still supports the SID keyword for purposes of backward compatibility, but the preferred keyword for specifying an instance is now INSTANCE_NAME. If you are running a Release 8.1 or higher, use the INSTANCE_NAME keyword as follows : (CONNECT_DATA = (INSTANCE_NAME = herman) ) Net8 also now allows you to specify a service name. For example: (CONNECT_DATA = (SERVICE_NAME = herman.gennick.org) ) The service name for a database instance is the combination of the SERVICE_NAMES and DB_DOMAIN parameters as specified in the instance's initialization file. Multiple instances can all implement the same service at the same time. The use of a service name is preferable when using Net8 to connect to an 8.1 or higher database because it removes the need to specify a specific instance in the tnsnames.ora file. 3.4.2.2 TCP/IP connections TCP/IP connections are made to a specific TCP/IP port on a specific host. The Net8 Listener must be running on the specified host, and it must be listening on the specified port. The address data for such a connection will look like this: (PROTOCOL = TCP)(HOST = hostname ip_address )(PORT = port_num ) where: - TCP
-
Identifies the protocol being used as TCP/IP. - hostname
-
Is the name of the server to which you are connecting. - ip_address
-
Is the IP address of the host (which you can specify as an alternative to the hostname). - port_num
-
Is the port number on which the Net8 Listener is listening. Typically, this is 1521. The HOST parameter specifies a host on which a Net8 Listener is running. You can name the host, in which case Net8 resolves the name using DNS, or you can hardcode an IP address. It's better to use a name, because that insulates you from changes to the host's IP address. The default port number for the Net8 Listener is 1521. If you're configuring a TCP/IP connection and aren't certain which port number to use, start with 1521. If that doesn't work, talk to your DBA. If you are the DBA, then look in the listener.ora file on the server to which you are trying to connect. You should see a DESCRIPTION entry resembling this one: (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = jonathan.gennick.org)(PORT = 1521)) (PROTOCOL_STACK = (PRESENTATION = TTC) (SESSION = NS) ) ) The address in the listener.ora file indicates the host on which the listener is running, and the port on which it is listening. To connect to this listener, you must use the identical address information in your net service name definition. 3.4.2.3 Bequeath connections A Bequeath connection is one that is made to a database on your local machine without going through the Net8 Listener. Normally, when you connect to a remote database, the listener creates a dedicated server process for your connection. Oracle's Bequeath protocol creates that server process for you directly, without the benefit of a listener. | | Bequeath is especially useful if you are running Personal Oracle, and you have applications that require a net service name in order to connect to a database. Define a net service name that uses the Bequeath connection, and provide that name to your applications. | | The address data for a Bequeath connection takes the following form: (PROTOCOL = BEQ)(PROGRAM = oracle_exe )(ARGV0 = sid_identifier ) (ARGS = '(DESCRIPTION=(LOCAL = YES)(ADDRESS = (PROTOCOL = BEQ)))') where: - BEQ
-
Identifies the protocol as Bequeath. - oracle_exe
-
Is the name of the Oracle executable on the server. In Linux and most Unix environments, a value of oracle should be used. It is not necessary to specify the extension. In Windows environments, releases of Oracle prior to 8.1 included the release number as part of the executable name. For Oracle 7.3, the executable is named oracle73 . For Oracle8 8.0, the executable is named oracle80 . Beginning with the Oracle8 i release, the executable name was changed to oracle , making the Windows releases more consistent with the Unix releases. - sid_identifier
-
Identifies the Oracle instance to which you are connecting, but in a rather odd way. It is actually the concatenation of the Oracle executable name with the SID name. To connect to the SID named ORCL on a machine running Personal Oracle8, you would use a value of oracle80ORCL . The CONNECT_DATA portion of the tnsnames.ora entry for a Bequeath connection may specify either an instance name or a service name, or both. For example, the following tnsnames.ora entry is taken from a Linux box and uses the service name to identify the database: donna-beq.gennick.org = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = BEQ)(PROGRAM = oracle) (ARGV0 = oracleDONNA) (ARGS = '(DESCRIPTION=(LOCAL=YES)(ADDRESS=(PROTOCOL=BEQ)))') ) ) (CONNECT_DATA = (SERVICE = DONNA.GENNICK.ORG)) ) There are two restrictions related to Bequeath connections. First, a dedicated server process is always created. Bequeath cannot be used in a multi-threaded server (MTS) mode. Second, you can only use Bequeath to connect to an Oracle instance running on the same machine. If you need to go across the network, you need to use TCP/IP, SPX, or some other network-based protocol. | | Oracle8 i , Release 8.1.5 for Windows NT does not support the use of the Bequeath protocol. The error messages that you get if you try to use Bequeath do not make this in any way clear, but it is documented in the release notes. If you are connecting to a local database on NT, look into using the IPC protocol instead. | | 3.4.2.4 IPC connections IPC is an acronym for Inter-Process Communications. Like Bequeath, the IPC protocol is used for connections to a database on a local machine. Communication between client software and server software is then accomplished using operating-system specific inter-process communications methods. Unlike the Bequeath protocol, use of the IPC protocol requires that a Net8 Listener be up and running. The address data for an IPC connection looks like this: (PROTOCOL = IPC)(KEY = key_name ) The key_name parameter may be any arbitrary alphanumeric name. It's simply a way of identifying a specific Net8 Listener. The key name used in a tnsnames.ora entry must match a DESCRIPTION entry in your server's listener.ora file that looks like this: (DESCRIPTION = (ADDRESS = (PROTOCOL = IPC)(KEY = key_name )) (PROTOCOL_STACK = (PRESENTATION = TTC) (SESSION = NS) ) ) Here's an example of a fully formed net service name definition from a tnsnames.ora file that uses the IPC protocol: HERMAN-IPC.GENNICK.ORG = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = IPC)(KEY = HERMAN)) ) (CONNECT_DATA = (SERVICE_NAME = HERMAN.GENNICK.ORG) ) ) Automatic IPC Releases of Net8 and SQL*Net prior to 8.1.5 supported an automatic IPC feature whereby connections to a local database could be automatically forced to use an IPC connection. For example, if you specified a net service name of herman, and you did not have a tnsnames.ora file on your system, Net8 would automatically generate the following IPC definition: (DESCRIPTION= (ADDRESS=(PROTOCOL=IPC)(KEY=herman)) (CONNECT_DATA=(SID=herman)) If your system did have a tnsnames.ora file, then Net8 would search that file for an entry that matched herman, pick the SID name out of that entry, and use that SID name as the value for KEY in an IPC connection attempt. The automatic IPC feature was controlled via a sqlnet.ora parameter named AUTOMATIC_IPC. The default setting was AUTOMATIC_IPC=ON, but you could disable the feature by setting AUTOMATIC_IPC=OFF. Beginning with Net8 Release 8.1.5, support for automatic IPC has been removed. | 3.4.2.5 SPX connections SPX is a protocol commonly used in Novell Netware environments. SPX is an acronym for Sequenced Packet Exchange . SPX connections are defined in terms of an SPX service name, and the address data takes the following form: (PROTOCOL = SPX)(SERVICE = spx_service_name ) The spx_service_name parameter is simply an arbitrary name that you choose when you configure the Net8 Listener on the server. It must match, for example, an entry in listener.ora that looks like this: (DESCRIPTION = (ADDRESS = (PROTOCOL = SPX)(SERVICE = herman)) (PROTOCOL_STACK = (PRESENTATION = TTC) (SESSION = NS) Here's an example of a tnsnames.ora entry that uses SPX to connect to a remote database: HERMAN-SPX.GENNICK.ORG = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = SPX)(SERVICE = herman)) ) (CONNECT_DATA = (SERVICE_NAME = herman.gennick.org) ) ) 3.4.2.6 Named Pipes connections Named Pipes is a protocol that allows interprocess communication across a network between clients and servers. Named Pipes is available in Microsoft Networking environments. The address data for a Named Pipes connection takes the following form: (PROTOCOL = NMP)(SERVER = server_name )(PIPE = pipe_name ) where: - NMP
-
Specifies that the Named Pipes protocol be used. - server_name
-
Is the name of the server running the Oracle8 i database. - pipe_name
-
Is the name of the pipe over which you want to communicate. The default name is ORAPIPE. In a Microsoft Networking environment, you can find out your server name by right-clicking the Network Neighborhood icon on your server's desktop, and then clicking the Identification tab in the resulting dialog. Look for the Computer Name field. The contents of that field represent the server name that you should use here. The pipe name may be any arbitrary name; however, it must match the name used in a DESCRIPTION entry in the server's listener.ora file. The server name must also be reflected in the DESCRIPTION entry. For example: (DESCRIPTION = (ADDRESS = (PROTOCOL = NMP)(SERVER = JONATHAN)(PIPE = ORAPIPE)) (PROTOCOL_STACK = (PRESENTATION = TTC) (SESSION = NS) ) ) In this example, the server is named JONATHAN, and the pipe is named ORAPIPE. The following net service name definition matches this DESCRIPTION entry: HERMAN-PIPE.GENNICK.ORG = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = NMP)(SERVER = JONATHAN)(PIPE = ORAPIPE)) ) (CONNECT_DATA = (SERVICE_NAME = herman.gennick.org) ) ) In order to use Named Pipes from a client machine, you need to have the Client for Microsoft Networks installed. If you don't see that entry listed in the Configuration tab of your Network control panel applet, then any attempt to create a Named Pipes connection will fail with a protocol adapter error. 3.4.3 Net8 Easy Config Net8 Easy Config is a GUI utility that walks you through the process of creating a new net service name entry in your tnsnames.ora file. Net8 Easy Config was introduced in one of the Oracle7 releases, and it is now considered to be a deprecated feature. Net8 Assistant can do everything that Net8 Easy Config can do, and more. To start Net8 Easy Config from Linux or Unix, enter the command netec . To start it under Windows, select Net8 Easy Config from the Start  Programs Oracle - OraHome81 Network Administration program group . Figure 3.9 shows the opening screen. Figure 3.9. Net8 Easy Config's opening screen  If either your tnsnames.ora file or sqlnet.ora file contains comments, you may get a warning from Net8 Easy Config. The warning will tell you that Net8 Easy Config may reposition or even delete your comments. We have had good luck with the latest version of this tool, and have never lost a comment. Of course, we can't guarantee that behavior. The choice of whether or not to continue is up to you. Net8 Easy Config presents you with four choices. You can create, modify, delete, or test a net service name. If you are deleting a service name, you just need to highlight the name in the Existing Net Service Names box, click Next, and confirm the deletion. If you are creating or modifying a net service name, subsequent screens lead you through the following tasks : Once you've done all this, Net8 Easy Config offers to test the new net service name by using it to log in to your database. The first login attempt is always made using SCOTT as a username and TIGER as a password. If you do not have this user defined in your database, the test will fail, and you will see the screen shown in Figure 3.10. Figure 3.10. Net8 Easy Config failed to log in as SCOTT/TIGER  From this screen you have the option to specify a different username and password for testing purposes. Click the Change Login button to do that, then click the Test button to try the test again. When you're finished testing, click the Next button. This takes you to the final screen where you must click Finish to make your change permanent. | | Net8 Easy Config does not store the username and password that you supply for testing purposesyou'll need to reenter it each time. This is a good thing. You don't want your database usernames and passwords laying around in operating-system files. | | 3.4.4 Net8 Assistant The Net8 Assistant is Oracle's GUI tool for configuring Net8. One of the many things that the Net8 Assistant allows you to do is to create and edit net service names. Net8 Assistant's functionality exceeds that of Net8 Easy Config, and you can use it to take advantage of advanced features such as client load balancing and failover. To start the Net8 Assistant under Linux or Unix, use the command netasst . To start it under Windows, select Net8 Assistant from the Start Programs Oracle - OraHome Network Administration program group. The opening screen will resemble that shown in Figure 3.11. Figure 3.11. Net8 Assistant lets you create, modify, test, and delete net service names from your tsnames.ora file  After you've started the Net8 Assistant, you can view a list of existing net service names by double-clicking the Net Service Names folder. Click on a specific name to highlight it, and then you'll see the details of that definition in the right-hand pane of the window. Figure 3.11 shows the definition for herman.gennick.org. Once you've highlighted a net service name, you can edit the definition in the right-hand pane of the window. You can also delete the name by clicking the red X on the left side of the window. Select Test Net Service Name from the Command menu in order to test a name. To create a new net service name using Net8 Assistant, click the green plus sign (+) on the left side of the window. That starts the Net Service Name Wizard, which looks exactly like Net8 Easy Config. The wizard will prompt you for the following information: -
The net service name to create -
The protocol to use -
The address details for the protocol that you choose -
The service name or SID for the database to which you want to connect The Net Service Name Wizard functions just like Net8 Easy Config, even to the point of asking you if you want to test your new connection. See the previous section on Net8 Easy Config for details on how the testing process works. Net8 Assistant allows you to specify more than one address for a net service name, which is necessary if you want to take advantage of advanced features such as client load balancing and failover. You can only specify one address when first creating a net service name. Once created, you can add more addresses by highlighting the name, and then clicking the green plus sign in the right-hand pane. After you've defined at least two addresses, the Advanced button in the Address Configuration area will be enabled. That button opens a dialog allowing you to tell Net8 how to use the addresses that you've defined. Read more about client load balancing and failover in Chapter 8. The Advanced button in the Service Identification area allows you to configure several advanced options related to the CONNECT_DATA parameters in the net service name definition. These are also described in Chapter 8. | 
