Understanding SQL*Net

Library

Product

Contents

Index

Syntax Rules for Configuration Files

• Keyword-Value Pair Syntax
• Further Syntax Rules for TNS Configuration Files
• Creating the LISTENER.ORA File
• Creating the TNSNAMES.ORA File
• Creating the SQLNET.ORA File for Clients and Servers
• Creating the PROTOCOL.ORA File
• Creating the TNSNAV.ORA File for Clients and Servers
• Further Examples

This appendix also includes information about the acceptable characters to use in various components of the files.

The contents of the files are described in detail in Appendix A.

Keyword-Value Pair Syntax

parameter = (keyword=value)

Some keywords have other keyword-value pairs as their values; in these cases, the group of keyword-value pairs that logically belong together are surrounded by parentheses:

(keyword=
	(keyword=value)
	(keyword=value)
)

For example, the address portion of a TNSNAMES.ORA file might include the following lines:

(ADDRESS=
	(COMMUNITY=tcpcom.hq.fin.acme)
	(PROTOCOL=tcp)
	(HOST=max)
	(PORT=1521) 
)

Oracle Corporation recommends that you set up the files so that indentation reflects what keyword is the "parent" or "owner" of other keyword-value pairs. This format is not required, but it does make the files much easier to read and understand. This is the format that Network Manager generates.

Even if you do not choose to indent your files in this way, you must indent a wrapped line by at least one space, or it will be misread as a new parameter. The following layout is acceptable:

(ADDRESS=(COMMUNITY=tcpcom.world)(PROTOCOL=tcp)
	(HOST=max.world)(PORT=1521))

The following layout is not acceptable:

(ADDRESS=(COMMUNITY=tcpcom.world)(PROTOCOL=tcp)
(HOST=max.world)(PORT=1521))

Further Syntax Rules for TNS Configuration Files

• Any keyword in a configuration file that should be recognized as beginning a parameter that includes one or more keyword-value pairs must be in the far left column of a line. If it is indented by one or more spaces, it is interpreted as a continuation of the previous line.

• All characters must belong to the network character set (see the next section).

• Keywords are not case sensitive. Values may be case sensitive, depending on the operating system and protocol.

• Spaces around the "=" sign are optional in keyword-value pairs.

• There is an implied hierarchy of keywords. That is, some keywords are always followed by other keywords. At any level of the hierarchy keywords can be listed in any order. For example, the following entries are equally valid:

(ADDRESS =
(COMMUNITY = TCPCOM.WORLD)
(PROTOCOL = TCP)
(HOST = MARTHA.WORLD)
(PORT = 1521)
)

(ADDRESS =
(COMMUNITY = TCPCOM.WORLD)
(PROTOCOL = TCP)
(PORT = 1521)
(HOST = MARTHA.WORLD)
)

• Keywords cannot contain spaces. Values must not contain spaces unless enclosed within double quotes ("). For example, the following is a valid value:

		(COMMUNITY = "West Central") 

• The maximum length of a connect descriptor is 512 bytes.

• Comments can be included using the pound sign # at the beginning of a line. Anything following the sign to the end of the line is considered a comment.

Network Character Set

		A-Z, a-z
		0-9
		( ) < > / \ 
		, . : ; ' " = - _ 
		$ + * # & ! % ? @ 

Within this character set, the following symbols are reserved:

		(  ) = \ " ' # 

Reserved symbols should be used only as delimiters, not as part of a keyword or a value unless the keyword or value is quoted. Either single or double quotes can be used to enclose a value containing reserved symbols. To include a quote within a value that is surrounded by quotes, use different quote types. The backslash (\) is used as an escape character.

A specific example of the use of reserved symbols is in a numeric DECnet object within a DECnet address. As defined by DECnet, an OBJECT can be a name such as ABC or a value such as #123. These would be entered in the form:

(OBJECT=ABC)

or

(OBJECT=\#123) 

The numeric DECnet object requires a symbol that is reserved by TNS. Because # is a reserved symbol, the character must be preceded by a backslash. See the Oracle Protocol Adapter information for your platform for further details on DECnet.

The following characters can be used within the structure of a connect descriptor, but cannot be part of a keyword or value:

		<space> <tab> <CR> <newline>

Service Name Character Set

[a...z] [A...Z] [0...9] _ 

The first character in a service name must be an alphabetic character. The number of characters allowed is platform specific; in general, however, up to 64 characters is acceptable. A database service name must match the global database name defined by the DBA. It consists of a database name (originally limited to eight characters), and the database domains. Service names and global database names are not case sensitive.

Note: Network Manager uses periods (.) when it appends domains to the names you enter, but it does not accept periods in the name you provide.

Creating the LISTENER.ORA File

Placement of the Listener Name

Defining the Listener Addresses

listener_name=[(ADDRESS_LIST=]
			(ADDRESS=
				[(COMMUNITY=community name)]
				(PROTOCOL=protocol name)
				(protocol specific information))
			[(ADDRESS=
				[(COMMUNITY=community name)]
				(PROTOCOL=protocol name)
				(protocol specific information)))] 

If the listener is listening on only one protocol, the ADDRESS_LIST keyword is not required; a single ADDRESS entry is sufficient. For a single community the form is:

listener_name=(ADDRESS=
			[(COMMUNITY=community name)]
			(PROTOCOL=protocol name)
			(protocol specific information)) 

The listener is able to listen on more than one protocol. For example, if the host machine is running both TCP/IP and DECnet (that is, it is in both a TCP/IP and a DECnet community), the listener on that machine has an address that includes both protocols.

IPC Addresses

Note: If the service name is the same as the SID, only one IPC address is needed, and only one is generated by Network Manager.

Sample Listener Addresses

LISTENER=(ADDRESS_LIST=
			(ADDRESS=
				(PROTOCOL=IPC)
				(KEY=ny_finance.hq.fin.acme)
			)
			(ADDRESS=
				(PROTOCOL=IPC)
				(KEY=db3)
			)
			(ADDRESS=
				(COMMUNITY=tcpcomm)
				(PROTOCOL=TCP)
				(HOST=flash.hq.fin.acme)
				(PORT=1521)
			)
			(ADDRESS=
				(COMMUNITY=deccomm.hq.fin.acme)
				(PROTOCOL=DECNET)
				(NODE=flash.hq.fin.acme)
				(OBJECT=LSNR)
			)
		) 

If you are creating the LISTENER.ORA file manually, and if there is only one community in your network, then the COMMUNITY keyword is optional for the listener, since listening is always performed on the local machine. You do, however, have the option to include it for consistency with your other connect descriptors. If you are using Network Manager you must provide the COMMUNITY keyword, but it is not included in the LISTENER.ORA file that is generated.

Describing the Databases on the Listener

SID_LIST_listener_name=[(SID_LIST=]
				(SID_DESC=
				   (GLOBAL_DBNAME=global_database_name)
				   (SID_NAME=SID)
				   (operating_system_specific_
				     string=db_location)
				)
				[(SID_DESC=
				   (GLOBAL_DBNAME=global_database_name)
				   (SID_NAME=SID)
				   (operating_system_specific_
				    string=db_location)
				)]
			    [)]

The SID_LIST keyword is required only if there is more than one database instance installed on the machine. In this format, SID is the Oracle system ID of the database server. In the next keyword-value pair, the keyword is operating system specific: it is indicated here as the variable operating_system_specific_string. Its value, indicated here as db_location, is the specific location of the database executables.

LISTENER.ORA Control Parameters

PARAMETER=value

Do not allow any empty spaces on the line before the parameter name. Parentheses do not need to surround the parameter-value pairs.

Creating the TNSNAMES.ORA File

Note: TNSNAMES.ORA file is not needed if the network includes Oracle Names.

Placement of the Service Names

Connect Descriptors

• the listener ADDRESS

• the CONNECT_DATA, which includes the database SID and, if you are using listener load balancing, the global database name.

ADDRESS Section

(ADDRESS= 
	(COMMUNITY=COM1.HQ.FIN.ACME) 
	(PROTOCOL=TCP) 
	(HOST=LONDON_VAX.HQ.FIN.ACME) 
	(PORT=1526)
) 

An address is a set of keyword-value pairs related to a specific application. The keyword ADDRESS is shown at a different indentation, to show that it is the parent or owner of the other keywords. Each set of keyword-value pairs is surrounded by parentheses as shown. In this example, the protocol is identified as TCP/IP. TCP/IP requires two specific parameters: the name of the host computer as defined in TCP/IP, and the PORT number allocated to the network listener. (This may vary depending on what Oracle Network Manager generates. For example, for TCP, the port 1526 might be generated. In SQL*Net version 1, the port was usually 1525.)

For the parameters specific to other protocols, see the Oracle operating system-specific documentation for your platform.

CONNECT DATA Section

(CONNECT_DATA= 
	(SID=V7PROD)
	(global_name=prod.acme.com
) 

CONNECT_DATA is a protocol-independent keyword indicating that application-specific data will be supplied at connect time. You must specify the SID in the CONNECT DATA section of the connect descriptor. In SQL*net 2.3, you are also expected to provide the global database name, which is made up of the database name and database domain from the database parameter file.

Interchange Addresses

There is no CONNECT_DATA section in the connect descriptor of an Interchange.

Note: Interchange names and addresses are optional in the TNSNAMES.ORA file. However, they are needed if you wish to access Interchanges from clients using the Interchange Control Utility. Oracle Network Manager automatically includes them in the TNSNAMES.ORA files it generates.

Creating the SQLNET.ORA File for Clients and Servers

Similarly, if you do not want to use IPC addresses and you do not want to use the multi-threaded server, you would add the following keyword-value pairs to the file:

AUTOMATIC_IPC = OFF
USE_DEDICATED_SERVER = ON

This syntax applies to all the parameters you might need to add manually to the SQLNET.ORA file.

If the network includes Oracle Names, the SQLNET.ORA file also contains addresses of the Names Servers preferred by the client or server. These addresses are entered by Network Manager and should not be edited. They have the same syntax as addresses in the LISTENER.ORA file described earlier. For example, a server in a TCP/IP community might have a preferred Names Server listed as follows:

names.preferred_servers =
	(ADDRESS_LIST =
		(ADDRESS =
			(PROTOCOL = TCP)
			(Host = iris.west.acme.com)
			(Port = 1522)
		)
	)
name.preferred_servers =
	(ADDRESS_LIST =
		(ADDRESS =
			(PROTOCOL = TCP)
			(Host = iris.west.acme.com)
			(Port = 1522)
		)
	)

The address is listed twice with slightly different keywords to provide backward compatibility to an earlier version.

Note: Do not edit the addresses of preferred Names Servers manually. Create and modify them using the Oracle Network Manager.

Creating the PROTOCOL.ORA File

Creating the TNSNAV.ORA File for Clients and Servers

LOCAL_COMMUNITIES

Format of TNSNAV.ORA

Sample LOCAL_ COMMUNITIES Entries

LOCAL_COMMUNITIES = (COMMUNITY_LIST =
				 (COMMUNITY = NMP.FIN.HQ.ACME)
				 (COMMUNITY = TCP.FIN.HQ.ACME)) 

For a client that is a member of just the Named Pipes community indicated, the following entries are equivalent:

LOCAL_COMMUNITIES = (COMMUNITY = NMP.FIN.HQ.ACME) 

and

LOCAL_COMMUNITIES = (COMMUNITY_LIST =
				 (COMMUNITY = NMP.FIN.HQ.ACME)) 

Keywords used within PREFERRED_CMANAGERS

PREFERRED_CMANAGERS=[(CMANAGER_LIST=] 
			    (CMANAGER= 
				(CMANAGER_NAME=cmanager_name) 
				(ADDRESS= 
				  (COMMUNITY=community_name) 
				  (PROTOCOL=protocol_ID) 
				  (protocol specific information))) 
			    [(CMANAGER= 
				(CMANAGER_NAME=cmanager_name) 
				(ADDRESS= 
				  (COMMUNITY=community_name) 
				  (PROTOCOL=protocol_ID) 
				  (protocol specific information)))]
 			  [ )]

In this syntax:

CMANAGER_LIST

Indicates that one or more descriptions of a Connection Manager follow, each identified by the keyword CMANAGER. This keyword is preceded by a left parenthesis, and finished with a right parenthesis following the last Connection Manager described. Where only one CMANAGER follows, this keyword is optional.

CMANAGER

Indicates that a Connection Manager is described following the keyword. The CMANAGER_NAME and the TNS address of the associated Connection Manager follow. At least one CMANAGER must be defined for any client or server that uses an Interchange.

CMANAGER_ NAME

Indicates the name of a Connection Manager. (The Connection Manager and the Interchange are usually referred to by the same name.)

ADDRESS

Indicates the address of the Connection Manager named in the CMANAGER_NAME parameter. Note that the Connection Manager has its own address for receiving connections on the Interchange machine. This is not the same as the address of a TNS listener if there is one on that machine.

Oracle Network Manager will supply the correct keywords and format for this configuration file; it will prompt you to supply the needed values for each CMANAGER_NAME and ADDRESS.

Sample TNSNAV.ORA File

LOCAL_COMMUNITIES =
  (COMMUNITY_LIST =
    (COMMUNITY = DECCOM.WORLD)
  )
PREFERRED_CMANAGERS =
  (CMANAGER_LIST =
    (CMANAGER =
      (CMANAGER_NAME = INT2.WORLD)
        (ADDRESS = 
          (COMMUNITY = DECCOM.WORLD)
          (PROTOCOL = DECNET)
          (NODE = IRIS.WORLD)
          (OBJECT = CMAN)
        )
    )
    (CMANAGER =
      (CMANAGER_NAME = INT1.WORLD)
        (ADDRESS = 
          (COMMUNITY = DECCOM.WORLD)
          (PROTOCOL = DECNET)
          (NODE = DAISY.WORLD)
          (OBJECT = CMAN)
        )
    )
  )

Further Examples

Prev Next

Copyright © 1996 Oracle Corporation. All Rights Reserved.

Library

Product

Contents

Index