Oracle Net8 Administrator's Guide Release 8.0 A58230-01 |
Library | Product | Contents | Index

# 8
Using Net8

Once you have completed configuring your network, you should start and test each component to ensure that they are functioning properly. Net8 provides a variety of tools to help you start, test and control a Names Server, network listener, and Connection Manager.

This chapter outlines procedures to use Net8's control utilities to operate each component once they have been configured. This chapter contains the following sections:

- Section 8.1, "Procedures to Get the Network Running"
- Section 8.2, "Net8 Component Testing Methodology"
- Section 8.3, "Net8 Control Utilities"
- Section 8.4, "Checklist for Troubleshooting Common Startup Problems"

## 8.1 Procedures to Get the Network Running

After installing and configuring all the network components, you need to start them to make the network functional. Following is an outline of the steps you should take to start the network components. For more detailed information about using the control utilities, refer to Appendix A, "Control Utility Reference"

1. If your network uses Oracle Names, start the Names Servers, using either the Oracle Net8 Assistant or the Oracle Names Control Utility.
   1. If the Names Servers use a database to store the network information, you will need to start the database first, then start the listener.
   2. If the Names Servers are not using a database, start a Names Server called "onames_oranamesrvr0", then issue a command to discover Names Servers on each Names Server node.
   3. Start each Names Server.
   4. Discover Names Servers on all client nodes.
2. Start the listeners using the Listener Control Utility. On each listener node, enter the following command:

       lsnrctl start

3. Start the databases, using the tool of your choice.
4. If your network includes Oracle Connection Managers, start them using the Connection Manager Control Utility. On each Oracle Connection Manager node, enter the following command:

       cmctl start cman

You should now be able to make connections across the network.

The remainder of this chapter provides more information about the control utilities, how to test connections between components, and how to resolve the most common problems.

## 8.2 Net8 Component Testing Methodology

The preferred sequence for testing the network is as follows:

- start and test each Names Server (if included in your network layout)
- start and test each listener
- start and test each Oracle Connection Manager (if included in your network layout)
- test each client by initiating a connection from the client to the server

## 8.3 Net8 Control Utilities

Net8 provides the following tools to help you start, test and control each network component.

- Oracle Names Control Utility - NAMESCTL
- Listener Control Utility - LSNRCTL
- Connection Manager Control Utility - CMCTL

For more information about Net8's component control utilities and their commands, refer to Appendix A, "Control Utility Reference".

##### Net8 Tools

In addition, Net8 provides the following tools to help you evaluate network connectivity:

- TNSPING
- TRCROUTE

### 8.3.1 Using the Oracle Names Control Utility (NAMESCTL)

The Oracle Names Control Utility, NAMESCTL, is a tool that you run from the operating system prompt to start and control the Names Server.

The general form of the Oracle Names Control Utility is:

NAMESCTL command

You can also issue NAMESCTL commands at the program prompt. When you enter NAMESCTL on the command line, the program is opened. You can then enter the desired commands from the program prompt. For example, the following command starts the Names Server.

    NAMESCTL> startup

The STARTUP command of NAMESCTL loads the Names Server into memory and tells it to begin executing. At startup, the Names Server loads its configuration and data. On each Names Server node, invoke NAMESCTL from the prompt to start the utility.

For additional information about NAMESCTL and its commands, refer to Appendix A, "Control Utility Reference".

#### 8.3.1.1 Starting a Names Server

To start a Names Server proceed as follows:

1. From the command line prompt type:

       NAMESCTL STARTUP

2. Or, from the NAMESCTL prompt, type:

       NAMESCTL> STARTUP

#### 8.3.1.2 Testing a Names Server

To test a Names Server, use the NAMESCTL PING command. Following are two ways to PING the Names Server LABRADOR in the US.ACME domain.

1. From the NAMESCTL prompt, type:

       NAMESCTL> PING LABRADOR.US.ACME

2. Or, from the NAMESCTL prompt, type:

       NAMESCTL> SET SERVER LABRADOR.US.ACME
       NAMESCTL> PING

You can test several Names Servers with the same PING command. For example:

    NAMESCTL>PING HUEY.UK.ACME DUEY.UK.ACME LOUIE.UK.ACME

PING responds with the time it takes to contact the Names Server and return an acknowledgment. If PING fails, make sure the Names Server is started or double-check the configured address of the Names Server.

#### 8.3.1.3 Test Network Objects Using NAMESCTL

To determine whether your listener, service name, database link, or any other network object has successfully registered itself with or become known to the Names Server, use the QUERY command.

From the NAMESCTL prompt, type:

    NAMESCTL> QUERY global_object_name type

Database service names have the type A.SMD, and database links have the type DL.RDBMS.OMD. The following example shows a query of the database service name BUGSY in the MACS.ACME domain.

    NAMESCTL> QUERY BUGSY.MACS.ACME A.SMD

The QUERY command returns the amount of time the transaction took and information about the network object.

### 8.3.2 Using the Listener Control Utility (LSNRCTL)

The Listener Control Utility, LSNRCTL, is a tool that you run from the operating system prompt to start and control the listener. The general form of the Listener Control Utility is:

    LSNRCTL command [listener_name] [args]

You can also issue Listener Control Utility commands at the program prompt. When you enter LSNRCTL on the command line, the program is opened. You can then enter the desired commands from the program prompt. For example, the following command determines the amount of time in seconds the listener will wait for a valid connection request after a connection has been started.

    LSNRCTL> set connect_timeout 20

For more information about LSNRCTL and its commands, refer to Section A.1 in Appendix A, "Control Utility Reference".

#### 8.3.2.1 Starting a Listener

You may start a listener on any node where Net8 is installed. To start a listener, use the Listener Control Utility, LSNRCTL, to issue a START command as follows:

    LSNRCTL START

To start a non-default listener:

    LSNRCTL START listener_name

LSNRCTL will display a status message indicating that the listener has started successfully. Check that all expected SIDs for that listener are listed in the services summary in the status message.

#### 8.3.2.2 Test a Listener

To test a listener, initiate a connection from a client to any active database controlled by that listener. If the only clients available to access the listener are on a different protocol, you must use an Oracle Connection Manager to access the listener.

### 8.3.3 Using the Connection Manager Control Utility (CMCTL)

The Connection Manager Control Utility, CMCTL, is a tool that you run from the operating system prompt to start and control Oracle Connection Manager. The general form of the Connection Manager Control Utility is:

    CMCTL command

You can also issue CMCTL commands at the program prompt. When you enter CMCTL on the command line, the program is opened. You can then enter the desired commands from the program prompt. For example, the following command starts Oracle Connection Manager.

    CMCTL> start

For more information about CMCTL and its commands, refer to Appendix A, "Control Utility Reference".

#### 8.3.3.1 Starting Oracle Connection Manager

You may start Oracle Connection Manager from any node where Net8 is installed. To start Oracle Connection Manager, use CMCTL to issue a START command as follows:

    CMCTL START CMAN

CMCTL displays a status message indicating that Oracle Connection Manager has started successfully.

#### 8.3.3.2 Testing Oracle Connection Manager

To test Oracle Connection Manager, initiate a connection from a client to any active database for which a source route address has been created.

### 8.3.4 Using TNSPING

TNSPING is a utility that determines whether or not a service (for example, an Oracle database, an Oracle Names Server or any other Oracle service) on a Net8 network can be successfully reached.

If you can connect successfully from a client to a server (or a server to another server) using TNSPING, it displays an estimate of the round trip time (in milliseconds) it takes to reach the Net8 service.

If it fails, it displays a message describing the error that occurred. This allows you to see the network error that is occurring without the overhead of a database connection.

#### 8.3.4.1 Starting TNSPING

To invoke the TNSPING utility, proceed as follows:

From the command line, type:

    tnsping service_name [count]

Note: Different platforms may have different interfaces, but the program accepts the same arguments. Invoke TNSPING for the display of the proper interface requirements.

- service name: must exist in TNSNAMES.ORA, Oracle Names, or the name service in use, such as NIS or DCE's CDS.
- count (optional): determines how many times the program attempts to reach the server.

If the service name specified is a database name, TNSPING attempts to contact the corresponding network listener. It does not actually determine whether or not the database itself is running. Use Server Manager to attempt a connection to the database.

#### 8.3.4.2 TNSPING Examples

Following are some examples of TNSPING. For example, to connect to a database named SPOTDB, the command:

    tnsping spotdb

produces the following message:

    TNS Ping Utility for SunOS:
    Copyright (c) Oracle Corporation 1997.  All rights reserved.
    Attempting to contact
    (ADDRESS=(PROTOCOL=TCP)(HOST=spot)(PORT=1521))
    OK (50msec)

To check whether a Names Server can be reached, use a command using the Net8 address as in the following:

    tnsping (ADDRESS=(PROTOCOL=TCP)(HOST=fido)(PORT=1575))

A message similar to the following will be returned to the user:

    TNS Ping Utility for SunOS:
    Copyright (c) Oracle Corporation 1997. All rights reserved.
    Attempting to contact (ADDRESS=(PROTOCOL=TCP)(HOST=fido)(PORT=1575))
    OK (70 msec)

To determine whether the STPRD database can be connected to, and to specify that TNSPING try to connect 10 times and then give up, use the following command:

    tnsping stprd 10

This command produces the following message:

    TNS Ping Utility for SunOS:
    Copyright (c) Oracle Corporation 1997. All rights reserved.
    Attempting to contact (ADDRESS=(PROTOCOL=TCP)(HOST=spot)(PORT=1521))
    OK (290 msec)
    OK (100 msec)
    OK (70 msec)
    OK (70 msec)
    OK (60 msec)
    OK (70 msec)
    OK (70 msec)
    OK (80 msec)
    OK (180 msec
    OK (340 msec)

Below is an example of TNSPING attempting to connect to an invalid service name:

    tnsping bad_db

This attempt produces the following message:

    TNS Ping Utility for SunOS:
    Copyright (c) Oracle Corporation 1997.  All rights reserved.
    TNS-03505: Failed to resolve name

Following is an example of using TNSPING to connect to a name that is valid, but that resolves to an address where no listener is located (for example, the listener may not be started):

    tnsping testing

The following message is returned:

    TNS Ping Utility for SunOS:
    Copyright (c) Oracle Corporation 1997.  All rights reserved.
    Attempting to contact (ADDRESS=(PROTOCOL=tcp)(HOST=spot)(PORT=1521))
    TNS-12541: TNS:no listener

### 8.3.5 Using TRCROUTE

The Trace Route Utility (TRCROUTE) enables administrators to discover what path or route a connection is taking from a client to a server. If TRCROUTE encounters a problem, it returns an error stack to the client instead of a single error. These additional error messages make troubleshooting easier.

TRCROUTE is different from TNSPING in that it travels as a special type of connect packet, and is routed as such. As it travels toward its destination, the TRCROUTE connect packet collects the TNS addresses of every node it travels through. If an error occurs, TRCROUTE collects error information that shows where the error occurred. The Trace Route Utility displays the information collected on the client screen. You can redirect the TRCROUTE output to a file, and print it if you wish.

#### 8.3.5.1 Requirements

Trace Route works only over Net8 and SQL*Net version 2.3 and later. Every node along the route from client to server must use SQL*Net version 2.3 or later. If a pre-2.3 node is on the path, the following error is displayed:

    TNS-03603:  Encountered a node with pre-2.3 version of SQL*Net

TRCROUTE shows what node along the path is responsible for any errors.

#### 8.3.5.2 Effect on Performance

The Trace Route Utility uses minimal resources. It gathers information in the connect data of a special connect packet; standard connect packets are not affected.

The server is not affected by TRCROUTE. The listener receives and processes the TRCROUTE connect packet. It returns the information to the client by putting it into a refuse packet. The server does not need to start up any new processes or deal with dummy connections.

#### 8.3.5.3 Starting the Trace Route Utility

To invoke TRCROUTE, type the following from the command line:

    trcroute service_name

If you have configured your network to use listener load balancing, there may be more than one listener on different nodes for a database. If so, the Trace Route Utility might use any of the listeners, just as a regular connection request might. The output it returns shows you what listener node it used.

#### 8.3.5.4 Examples of Trace Route Output

The following are two examples of trace route output:

- a successful Trace Route packet that traveled from a client to a listener
- an unsuccessful Trace Route packet that could not reach the listener because the listener was not up.

  #### Example 8-1 Successful Trace Route

####

    %trcroute tcp_direct
    Trace Route Utility for Solaris:
    Copyright (c) Oracle Corporation 1997.  All rights reserved.

    Route of TRCROUTE:------------------
    Node: Client            Time and address of entry into node:
    -------------------------------------------------------------
    01-DEC-96 13:26:36 ADDRESS= PROTOCOL=TCP  Host=shining-sun  Port=1581
    Node: Server            Time and address of entry into node:
    -------------------------------------------------------------
    01-DEC-96 13:27:20 ADDRESS= PROTOCOL=TCP  Host=setting-sun  Port=1521

    Example 8-2 Trace Route with Error
    % trcroute tcp_direct

    Trace Route Utility for SVR4:
    Copyright (c) Oracle Corporation 1996.  All rights reserved.

    Route of TRCROUTE:------------------
    Node: Client            Time and address of entry into node:
    -------------------------------------------------------------
    01-DEC-96 11:12:34 ADDRESS= PROTOCOL=TCP  Host=shining-sun  Port=1581
    TNS-12224: TNS:no listener
    TNS-12541: TNS:no listener
    TNS-12560: TNS:protocol adapter error
    TNS-03601: Failed in route information collection

### 8.3.6 Testing a Client

To test several different clients in your network, initiate a connection to a server from each of them. If the connection is unsuccessful, use logging and tracing (including TRCROUTE), to find the cause of the problem.

There are a number of ways to initiate a connection to an Oracle server. Commonly used methods include:

- the operating system command line
- a tool logon screen
- a 3GL program
- special commands within certain tools

The specifics of use are slightly different in each case. Each of the general methods listed is briefly covered here. To identify the method used in a specific tool, refer to the tool's user's guide.

#### 8.3.6.1 Connecting from the Operating System to Test a Client

The general form of connecting an application to a database server from the command line is:

    tool username/password@service_name

To prevent the password from displaying during a logon, you can leave out the password parameter on the command line; you will be prompted to enter your password without it showing on screen.

Most Oracle tools can use the operating system command line to connect; some provide alternatives.

#### 8.3.6.2 Connecting from the Tool Logon Screen to Test a Client

Some tools provide a logon screen as an alternative form of logon. A user can log on to a database server by identifying both the username and service name (username@service_name) in the username field of the tool logon screen, and typing the password as usual in the password field.

#### 8.3.6.3 Connecting from 3GL to Test a Client

In applications written using 3GL, the program must establish a connection to a server using the following syntax:

    EXEC SQL CONNECT :username IDENTIFIED BY :password

In this connection request, the :username and :password are 3GL variables that can be set within the program either statically or by prompting the user. When connecting to a database server, the value of the :username variable is in the form:

    username@service_name

The :password variable contains the password for the database account being connected to.

#### 8.3.6.4 Connecting Using Special Commands within Tools

Some Oracle tools have commands for database connection, once the tool has been started, to allow an alternative username to be specified without leaving the tool. Both SQL*Plus and SQL*DBA allow the CONNECT command using the following syntax:

    SQL> CONNECT username/password@service_name

For example:

    SQL> CONNECT SCOTT/TIGER@SERVERX

This is very similar to the operating system command line method, except that it is entered in response to the tool prompt instead of the operating system prompt.

Other Oracle tools use slightly different methods specific to their function or interface. For example, Oracle CDE tools use logon buttons and a pop-up window with the username, password, and remote database ID field. For more information on connecting to Oracle with a specific tool, refer to the tool's user guide.

## 8.4 Checklist for Troubleshooting Common Startup Problems

The following checklist is provided to help you troubleshoot common problems you may encounter when starting Net8 components.

##### Table 8-1 Common Problems Encountered When Starting Net8 Components

Cause | Action
--- | ---
Inactive Components | Verify that you have installed a transport layer protocol and an Oracle Protocol Adapter. Verify that you have started a listener for any server you intend to contact. Start Oracle Connection Manager if you are routing sessions across protocols.
Syntax errors in your configuration files | Use the Oracle Net8 Assistant whenever possible to avoid syntax errors. If you have manually created or edited configuration files, check them carefully to ensure that all the appropriate parentheses are in place, that the lines are indented to show their logical structure, and that there are no typographical errors. For details on the syntax of these files, refer to the section titled, "Syntax Rules for Configuration Files" in Appendix B, "Configuration Parameters". Verify that all service names are mapped to connect descriptors in any applicable local naming configuration file. Verify that an invalid listener name was not typed in the LSNRCTL START command. Check your typing. Verify that the listener name you are using matches the name specified in your listener configuration file (LISTENER.ORA).
Files are incorrectly placed. | The listener will indicate that it cannot start because configuration files could not be found. Normally, all configuration files are stored in $ORACLE_HOME/network/admin. However, the environment variable, TNS_ADMIN, can be set to point to a different location. If $TNS_ADMIN is set to a different directory, Net8 will expect your configuration files to exist in that directory. Secondly, Net8 looks in a "home" directory for configuration files. The "home" directory is different for each operating system. The best way to tell the location of the files is to look in your SQLNET.LOG file or in the header information in your trace file if you have asked for tracing to be turned on. If you are using Names Servers, verify that they have been started. Also make sure that your profile contains a preferred Names Server parameter so that a Names List file exists. If a native naming service such as NIS is in use, make sure that the appropriate Native Naming adapter has been installed on clients and servers, and that service names have been properly loaded into it. Refer to your operating system-specific documentation for information.
The address is already in use. | Another process may already be using the address listed in the listener configuration file (LISTENER.ORA). On some protocols such as TCP/IP, DECnet, and OSI, each network service on a node must use a unique port or socket. On other network protocols such as SPX/IPX or NetBIOS, each network service name must be unique for the entire network. Another network service may be using the same configuration. Contact your network administrator to evaluate whether the network address is available.
When trying to connect to a database, you may get the message `ORA-12203: "TNS:Unable to connect to destination".` | Use the Listener Control Utility (LSNRCTL) to start the listener.
When trying to make a connection from a client, you may get the message `ORA-12154:"TNS:Could not resolve service name"`. | The service name you requested is not defined in your Oracle Names Server, Native Naming adapter, or local naming configuration file, or the local naming file can not be found as expected. If you are using Oracle Names, this problem may indicate a Names Server definition problem. Verify that your profile contains a NAMES.DIRECTORY_PATH parameter for a list of naming methods. Server is not running A Names Server List file does not exist. Issue a REORDER_NS command from NAMESCTL. The NAMES.PREFERRED_SERVER parameter is not configured correctly in a local profile. Verify that the parameter is configured correctly in the local profile.
When trying to connect to a database, you may get the message `ORA-1034: "Oracle Not Available"`, or `ORA-12505: "Listener could not resolve SID given in connect descriptor"`. | The database is not running on the server machine. A listener alone does not provide a database connection; the database instance must also be started.
A client returns the message "ORA-12541: No Listener". | Connect requests that come in too quickly for a listener to handle, and which exceed the listener's backlog (determined by QUEUESIZE parameter in LISTENER.ORA and NAMES.ORA), are returned with an ECONNREFUSED error. A client encountering this error returns the message "ORA-12541: No Listener" and the client log or trace files will show the ECONNREFUSED message. To correct this problem, follow these steps: Stop the listener. Reconfigure QUEUESIZE in your listener (LISTENER.ORA), Oracle Connection Manager (CMAN.ORA), or Names Server (NAMES.ORA) configuration files to be a larger value (based on anticipated simultaneous connect requests). Restart the listener. Try to connect again.
When attempting to stop the listener, you may get the message TNS-01169: "The listener has not recognized the password." | Enter the SET PASSWORD command from within the Listener Control Utility (LSNRCTL), and then enter the STOP command to stop the listener.

Prev | Next
| Copyright © 1997 Oracle Corporation. All Rights Reserved. |
Library | Product | Contents | Index