12
Configuring and Administering the Listener

The listener is a separate process that runs on the database server computer. It receives incoming client connection requests and manages the traffic of these requests to the database server. This chapter describes how to configure the listener to accept client connections.

This chapter contains these topics:

• Listener Configuration Overview
• Listener Configuration During Installation
• Customizing Listener Configuration
• Configuring Service Registration
• Listener Administration

  See Also: Chapter 2, "Connectivity Concepts" for a description of how the listener is used during an initial connection request Chapter 4, "Architecture of Oracle Net Services" for an architectural overview of the listener

Listener Configuration Overview

Note: A version 9 listener is required for an Oracle9i database. Previous versions of the listener are not supported for use with an Oracle9i database. However, it is possible to use a version 9 listener with previous versions of the Oracle database.

A listener is configured with one or more listening protocol addresses, information about supported services, and parameters that control its runtime behavior. The listener configuration is stored in a configuration file named listener.ora.

Because all of the configuration parameters have default values, it is possible to start and use a listener with no configuration. This default listener has a name of LISTENER, supports no services upon startup, and listens on the following TCP/IP protocol address:

(ADDRESS=(PROTOCOL=tcp)(HOST=host_name)(PORT=1521))

Supported services, that is, the services to which the listener forwards client requests, can be configured in the listener.ora file or this information can be dynamically registered with the listener. This dynamic registration feature is called service registration and is used by Oracle9i or Oracle8i instances. The registration is performed by the PMON process--an instance background process--of each database instance that has the necessary configuration in the database initialization parameter file. Dynamic service registration does not require any configuration in the listener.ora file.

See Also: "Listener Architecture"

Service registration offers the following benefits:

• Simplified configuration

  Service registration reduces the need for the SID_LIST_listener_name parameter setting, which specifies information about the databases served by the listener, in the listener.ora file.

  Note: The SID_LIST_listener_name parameter is still required if you are using Oracle Enterprise Manager to manage the database.

• Connect-time failover

  Because the listener always knows the state of the instances, service registration facilitates automatic failover of the client connect request to a different instance if one instance is down.

  In a static configuration model, a listener would start a dedicated server upon receiving a client request. The server would later find out that the instance is not up, causing an "Oracle not available" error message.

• Connection load balancing

  Service registration enables the listener to forward client connect requests to the least loaded instance and dispatcher or dedicated server. Service registration balances the load across the service handlers and nodes.

Oracle Enterprise Manager tools require static service configuration in the listener.ora file.

See Also: "Listener Architecture" "Configuring Service Registration" "Configuring Address List Parameters" "Configuring Connection Load Balancing"

Listener Configuration During Installation

Oracle Universal Installer launches Oracle Net Configuration Assistant during software installation. Oracle Net Configuration Assistant enables you to configure the listening protocol address and service information for an Oracle database.

During an Enterprise Edition or Standard Edition installation on the database server, Oracle Net Configuration Assistant automatically configures a listener with a name of LISTENER that has a TCP/IP listening protocol address for the Oracle database. During a Custom installation, Oracle Net Configuration Assistant prompts you to configure a listener name and a protocol address of your choice.

Additionally, a listening IPC protocol address for external procedure calls is automatically configured, regardless of the installation type.

Oracle Net Configuration Assistant also automatically configures service information for the Oracle database and the external procedures in the listener.ora file.

Note: While service information is not required in the listener.ora file, Oracle Net Configuration Assistant assumes that you are using Oracle Enterprise Manager to monitor the database. Oracle Enterprise Manager requires this information to discover the database.

Figure 12-1 shows a listener.ora file sample. The LISTENER entry defines the listening protocol address for a listener named LISTENER, and the SID_LIST_LISTENER entry provides information about the services supported by the listener LISTENER.

Figure 12-1 Example listener.ora File

LISTENER=
  (DESCRIPTION=
    (ADDRESS_LIST=
      (ADDRESS=(PROTOCOL=tcp)(HOST=sale-server)(PORT=1521))
      (ADDRESS=(PROTOCOL=ipc)(KEY=extproc))))
SID_LIST_LISTENER=
  (SID_LIST=
    (SID_DESC=
      (GLOBAL_DBNAME=sales.us.acme.com)
      (ORACLE_HOME=/oracle9i)
      (SID_NAME=sales))
    (SID_DESC=
      (SID_NAME=plsextproc)
      (ORACLE_HOME=/oracle9i)
      (PROGRAM=extproc)))

See Also: Oracle9i Net Services Reference Guide for further information about identifying listeners by unique names and creating multiple listener entries in the listener.ora file

Customizing Listener Configuration

If the default or installed configuration is not adequate for a particular environment, you can use Oracle Net Manager to customize the listener.ora configuration.

This section contains these configuration topics:

• Configuring Listening Protocol Addresses
• Configuring Access to Oracle JServer
• Configuring Static Service Information
• Configuring Password Authentication for the Listener

Configuring Listening Protocol Addresses

To configure additional protocol addresses for the listener:

1. Start Oracle Net Manager.

   See Also: "Starting Oracle Net Manager"

2. In the navigator pane, expand Local > Listeners.
3. Select a listener.

   Note: If a listener.ora file has been configured, but the listener has never been started with the Listener Control utility, the Listeners folder does not display a listener. If this occurs, exit Oracle Net Manager, start the listener, as described in "Starting Oracle Net Services Components", and start Oracle Net Manager again.

   If a listener has never been created:

   1. Click plus (+) from the toolbar, or choose Edit > Create.

      The Choose Listener Name dialog box appears.

   2. Enter a unique listener name in the Listener Name field.
   3. Click OK.
4. From the list in the right pane, select Listening Locations.
5. Click Add Address.

   A new Address tab appears.

6. Select a protocol, and then enter the appropriate parameter information for the selected protocol in the fields provided.

   See Also: Oracle9i Net Services Reference Guide for protocol parameter settings

   When configuring the listener to listen on TCP/IP, you should enter the default port of 1521. If you do not, you must configure the LOCAL_LISTENER parameter in the initialization parameter file and resolve the listener name through a naming method.

   See Also: Oracle9i Net Services Reference Guide for further information about protocol addresses and TCP/IP privileged ports "Registering Information with a Nondefault Listener"

   If the computer has more than one IP address and you want the listener to listen on all available IP addresses, configure TCP/IP or TCP/IP with SSL and enter the host name of the computer in the Host field.

7. Repeat Steps 5 and 6 for additional protocols.
8. Choose File > Save Network Configuration.

Configuring Access to Oracle JServer

Clients access Enterprise JavaBeans (EJBs) and Common Object Request Broker Architecture (CORBA) applications, provided with the Oracle JServer option, in an Oracle8i database over an Inter-Orb Protocol (IIOP) connection. IIOP is an implementation of General Inter-Orb Protocol (GIOP) over TCP/IP. To support access to CORBA and EJB, you configure the listener with a protocol address with port 2481 for TCP/IP or port 2482 for TCP/IP with SSL.

To configure a protocol address for Oracle JServer in an Oracle8i database:

1. Start Oracle Net Manager.

   See Also: "Starting Oracle Net Manager"

2. In the navigator pane, expand Local > Listeners.
3. Select a listener.

4. From the list in the right pane, select Listening Locations.
5. Click Add Address.

   A new Address tab appears.

6. Select the TCP/IP or TCP/IP with SSL protocol from the Protocol list.
7. Enter the host name of the database in the Host field.
8. Enter port 2481 for TCP/IP in the Port field, or enter port 2482 for TCP/IP with SSL in the Port field.
9. Click Statically dedicate this address for JServer connections.
10. Choose File > Save Network Configuration.

    The listener.ora file updates with the following:

    listener=
     (DESCRIPTION_LIST=
      (DESCRIPTION=
       (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-server)(PORT=2481))
       (PROTOCOL_STACK=
         (PRESENTATION=giop)
         (SESSION=raw))))
    

    See Also: Oracle8i Enterprise JavaBeans Developer's Guide and Reference for complete instructions for configuring client connections to EJB and CORBA applications

Handling Large Volumes of Concurrent Connection Requests

If you expect the listener to handle large volumes of concurrent connection requests, then you can specify a listener queue size for its TCP/IP listening endpoints. To specify the listener queue size, specify the QUEUESIZE parameter at the end of the protocol address with its value set to the expected number of concurrent requests. For example:

Figure 12-2 listener.ora File with Queue Size

LISTENER=
 (DESCRIPTION=
  (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521)(QUEUESIZE=20)))

Note:: The default number of concurrent connection requests is system specific. Following are the defaults for the Solaris Operating System and Windows NT: Solaris Operating System: 5 Windows NT 4.0 Workstation: 5 Windows NT 4.0 Server: 50

Configuring Static Service Information

In order for the listener to accept client connect requests to an Oracle8 release 8.0 or Oracle7 database, you must configure the listener.ora file with information about the database. Static configuration is also required for other services, such as external procedures, Heterogeneous Services, and some management tools, including Oracle Enterprise Manager.

For Oracle9i and Oracle8i databases, the listener uses the dynamic service information about the database and instance it has received through service registration before using statically configured information in the listener.ora file.

Table 12-1 describes static service settings that you can set in the listener.ora file.

Table 12-1  Static Service Settings in listener.ora

Oracle Net Manager Field	listener.ora File Parameter	Description
SID	SID_NAME	Use to specify the Oracle System Identifier (SID) of the instance. You can obtain the SID value from the INSTANCE_NAME parameter in the initialization parameter file.
Global Database Name	GLOBAL_DBNAME	Use to identify the database service. While processing a client connection request, the listener tries to match the value of this parameter with the value of the SERVICE_NAME parameter in the client connect descriptor. If the client connect descriptor uses the SID parameter, then the listener does not attempt to map the values. This parameter is primarily intended for configurations with Oracle8 release 8.0 or Oracle7 databases (where dynamic service registration is not supported for dedicated servers). This parameter may also be required for use with Oracle9i and Oracle8i database services by some configurations and management tools. The value for this parameter is typically obtained from the combination of the DB_NAME and DB_DOMAIN parameters (DB_NAME.DB_DOMAIN) in the initialization parameter file, but the value can also contain any valid name used by clients to identify the service.
Oracle Home Directory	ORACLE_HOME	On UNIX, this setting is optional. Use it specify the Oracle home location of the instance. Without this setting, the listener assumes its Oracle home for the instance. On Windows NT, this settings is ignored. The Oracle home specified by the ORACLE_HOME parameter in HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\HOMEID of the Windows NT registry is used.

Important: If you are using connect-time failover or Transparent Application Failover (TAF), such as in an Oracle9i Real Application Cluster environment, then do no set the GLOBAL_DBNAME parameter.

See Also: "Configuring Service Registration" for more information about configuring dynamic service registration of Oracle9i and Oracle8i databases Chapter 15, "Enabling Advanced Features of Oracle Net Services" for more information about statically configuring the listener for external procedures and Heterogeneous Services Oracle Enterprise Manager Configuration Guide for further information about Oracle Enterprise Manager

To statically configure the listener:

1. Start Oracle Net Manager.

   See Also: "Starting Oracle Net Manager"

2. In the navigator pane, expand Local > Listeners.
3. Select a listener.
4. From the list in the right pane, select Database Services.
5. Click Add Database.

   A new Database tab appears.

   

   Text description of the illustration listenea.gif

   See Also: Table 12-1 for a description of the fields

6. Enter the global database name, location of the Oracle home directory, and the SID of the instance in the appropriate fields.
7. Choose File > Save Network Configuration.

   For example, an excerpt of a listener.ora file statically configured for a database service called sales.us.acme.com looks like this:

   SID_LIST_listener=
   (SID_LIST=
    (SID_DESC=
     (GLOBAL_DBNAME=sales.us.acme.com)
     (SID_NAME=sales)
     (ORACLE_HOME=/u01/app/oracle/9i)))
   

Configuring Password Authentication for the Listener

Note: If you are administering the listener remotely over an insecure network and require maximum security, configure the listener with a secure protocol address that uses the TCP/IP with SSL protocol. If the listener has multiple protocol addresses, ensure that the TCP/IP with SSL protocol address is listed first in the listener.ora file.

It is important to provide security through a password for the listener. With a password, privileged operations, such as saving configuration changes or stopping the listener, used from the Listener Control utility will require a password.

Use the Listener Control utility's CHANGE_PASSWORD command or the Oracle Net Manager to set or modify an encrypted password in the PASSWORDS_listener_name parameter in the listener.ora file. If the PASSWORDS_listener_name parameter is set to an unencrypted password, you must manually remove it from the listener.ora file prior to modifying it. If the unencrypted password is not removed, you will be unable to successfully set an encrypted password.

To set or modify an encrypted password with Oracle Net Manager:

1. In the navigator pane, expand Local > Listeners.
2. Select a listener.
3. From the list in the right pane, select General Parameters.
4. Select the Authentication tab.
5. Click Require a Password for Listener Operations.
6. Enter the password in the Password field, and re-enter it in the Confirm Password field.
7. Choose File > Save Network Configuration.

To set a new encrypted password with the CHANGE_PASSWORD command, issues the following commands from the Listener Control utility:

LSNRCTL> CHANGE_PASSWORD
Old password: <enter>New password: password
Reenter new password: password
LSNRCTL> SAVE_CONFIG

Bold denotes user input. The password is not displayed when entered.

To modify an encrypted password with the CHANGE_PASSWORD command:

LSNRCTL> CHANGE_PASSWORD
Old password: password
New password: password
Reenter new password: password
LSNRCTL> SAVE_CONFIG

See Also: Oracle9i Net Services Reference Guide for further information about the CHANGE_PASSWORD command

Configuring Service Registration

For Oracle9i and Oracle8i databases, the listener uses the dynamic service information about the database and instance it has received through service registration before using statically configured information in the listener.ora file. Dynamic service registration is configured in the database initialization file. It does not require any configuration in the listener.ora file. However, listener configuration must be synchronized with the information in the database initialization file.

This section contains the following configuration topics related to service registration:

• Configuring Service Registration
• Registering Information with the Default, Local Listener
• Registering Information with a Nondefault Listener
• Registering Information with a Remote Listener
• Configuring a Naming Method

Configuring Service Registration

To ensure service registration works properly, the initialization parameter file should contain the following parameters:

• SERVICE_NAMES for the database service name
• INSTANCE_NAME for the instance name

For example:

SERVICE_NAMES=sales.us.acme.com
INSTANCE_NAME=sales

The value for the SERVICE_NAMES parameter defaults to the global database name, a name comprising the DB_NAME and DB_DOMAIN parameters in the initialization parameter file, entered during installation or database creation. The value for the INSTANCE_NAME parameter defaults to the SID entered during installation or database creation.

See Also: Oracle9i Database Reference for further information about the SERVICE_NAMES and INSTANCE_NAME parameters

Registering Information with the Default, Local Listener

By default, the PMON process registers service information with its local listener on the default local address of TCP/IP, port 1521. As long as the listener configuration is synchronized with the database configuration, PMON can register service information with a nondefault local listener or a remote listener on another node. Synchronization is simply a matter of specifying the protocol address of the listener in the listener.ora file and the location of the listener in the initialization parameter file.

Registering Information with a Nondefault Listener

If you want PMON to register with a local listener that does not use TCP/IP, port 1521, configure the LOCAL_LISTENER parameter in the initialization parameter file to locate the local listener.

For a shared server environment, you can alternatively use the LISTENER attribute of the DISPATCHERS parameter in the initialization parameter file to register the dispatchers with a nondefault local listener. Because both the LOCAL_LISTENER parameter and the LISTENER attribute enable PMON to register dispatcher information with the listener, it is not necessary to specify both the parameter and the attribute if the listener values are the same.

Set the LOCAL_LISTENER parameter as follows:

LOCAL_LISTENER=listener_alias

Set the LISTENER attribute as follows:

DISPATCHERS="(PROTOCOL=tcp)(LISTENER=listener_alias)"

listener_alias is then resolved to the listener protocol addresses through a naming method, such as a tnsnames.ora file on the database server.

For example, if the listener is configured to listen on port 1421 rather than port 1521, you can set the LOCAL_LISTENER parameter in the initialization parameter file as follows:

LOCAL_LISTENER=listener1

Using the same listener example, you can set the LISTENER attribute as follows:

DISPATCHERS="(PROTOCOL=tcp)(LISTENER=listener1)"

You can then resolve listener1 in the local tnsnames.ora as follows:

listener1= 
 (DESCRIPTION= 
  (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1421)))

Notes: To dynamically update the LOCAL_LISTENER parameter, use the SQL statement ALTER SYSTEM SET: ALTER SYSTEM SET LOCAL_LISTENER='listener_alias' If you set the parameter to null with the statement that follows, then the default local address of TCP/IP, port 1521 is assumed. ALTER SYSTEM SET LOCAL_LISTENER='' See the Oracle9i SQL Reference for further information about the ALTER SYSTEM SET statement. The LISTENER attribute overrides the LOCAL_LISTENER parameter. As a result, the SQL statement ALTER SYSTEM SET LOCAL_LISTENER does not affect the setting of this attribute.

To register information with another local listener:

1. Configure the listener.ora file with the protocol address of the local listener.

   See Also: "Configuring Listening Protocol Addresses"

2. Configure the LOCAL_LISTENER parameter in the initialization parameter file to locate the local listener. If you are using shared server, you can also use the LISTENER attribute of the DISPATCHERS parameter in the initialization parameter file.
3. Resolve the listener name alias for the LOCAL_LISTENER or the LISTENER setting through a tnsnames.ora file or an Oracle Names server.

   See Also: "Configuring a Naming Method"

Registering Information with a Remote Listener

Registration to remote listeners, such as in the case of Oracle9i Real Application Clusters, can be configured for shared server or dedicated server environments.

If you want PMON to register with a remote listener, configure the REMOTE_LISTENER parameter in the initialization parameter file to locate the remote listener.

For a shared server environment, you can alternatively use the LISTENER attribute of the DISPATCHERS parameter in the initialization parameter file to register the dispatchers with any listener. Because both the REMOTE_LISTENER parameter and the LISTENER attribute enable PMON to register dispatcher information with the listener, it is not necessary to specify both the parameter and the attribute if the listener values are the same.

Set the REMOTE_LISTENER parameter as follows:

REMOTE_LISTENER=listener_alias

Set the LISTENER attribute as follows:

DISPATCHERS="(PROTOCOL=tcp)(LISTENER=listener_alias)"

listener_alias is then resolved to the listener protocol addresses through a naming method, such as a tnsnames.ora file on the database server.

For example, if separate listeners are configured to listen on port 1521 on servers sales1-server and sales2-server, you can set the REMOTE_LISTENER parameter in the initialization file for the instance on host sales1-server as follows:

REMOTE_LISTENER=listener_sales2

You can set the REMOTE_LISTENER parameter in the initialization file for the instance on host sales2-server as follows:

REMOTE_LISTENER=listener_sales1

You can then resolve listener_sales2 in the local tnsnames.ora on sales1-server as follows:

listener_sales2= 
 (DESCRIPTION= 
   (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-server)(PORT=1521)))

Likewise, you can resolve listener_sales1 in the local tnsnames.ora on sales2-server as follows:

listener_sales1= 
 (DESCRIPTION= 
   (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-server)(PORT=1521)))

If shared server is configured, you can set the DISPATCHERS parameter in the initialization parameter file as follows:

DISPATCHERS="(PROTOCOL=tcp)(LISTENER=listeners_sales)"

You can then resolve listener_sales in the local tnsnames.ora as follows:

listeners_sales= 
 (DESCRIPTION= 
   (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-server)(PORT=1521))
   (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-server)(PORT=1521)))

Notes: To dynamically update the REMOTE_LISTENER parameter, use the SQL statement ALTER SYSTEM SET: ALTER SYSTEM SET REMOTE_LISTENER='listener_alias' If you set the parameter to null with the statement that follows, then PMON de-registers information with the remote listener with which it had previously registered information. ALTER SYSTEM SET REMOTE_LISTENER='' See the Oracle9i SQL Reference for further information about the ALTER SYSTEM SET statement. The LISTENER attribute overrides the REMOTE_LISTENER parameter. As a result, the SQL statement ALTER SYSTEM SET REMOTE_LISTENER does not affect the setting of this attribute.

To register information with remote listener:

1. Configure the listener.ora file with the protocol addresses of the remote listeners.

   See Also: "Configuring Listening Protocol Addresses"

2. In a shared server environment, configure the LISTENER attribute of the DISPATCHERS parameter or the REMOTE_LISTENER parameter in the initialization parameter file. In a dedicated server environment, configure the REMOTE_LISTENER parameter in the database initialization parameter file.

3. Resolve the listener name alias for the LISTENER or the REMOTE_LISTENER setting through a tnsnames.ora file or an Oracle Names server.

   See Also: "Configuring a Naming Method"

Configuring a Naming Method

The listener name alias specified for the LOCAL_LISTENER parameter, REMOTE_LISTENER parameter, or LISTENER attribute can be resolved through one of the following naming methods:

• tnsnames.ora File
• Oracle Names Server

tnsnames.ora File

A net service name entry should be created for the protocol address without the CONNECT_DATA section of the connect descriptor. Oracle Net Manager does not enable you to configure a tnsnames.ora file without the CONNECT_DATA information. Therefore, Oracle Corporation recommends that you manually modify the tnsnames.ora file.

For example, if LOCAL_LISTENER is set to listener1 and listener1 uses TCP/IP on port 1421, the entry in the tnsnames.ora file would be:

listener1= 
  (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1421))

Note: Multiple addresses are supported, but connect-time failover and client load balancing features are not supported.

See Also: Chapter 15, "Enabling Advanced Features of Oracle Net Services" for further information about multiple address configuration

Oracle Names Server

An entry for the listener alias name can be made to an Oracle Names server through Oracle Net Manager:

1. Start Oracle Net Manager.

   See Also: "Starting Oracle Net Manager"

2. In the navigator pane, expand Oracle Names Servers.
3. Select the Oracle Names server.
4. From the list in the right pane, select Manage Data.
5. Click the Advanced tab.
6. Click Add, enter the listener alias name in the Name field, A.SMD record type in the Type field, and enter the address in the Value field, for example:

   (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=2481))
   
   

7. Choose File > Save Network Configuration.

Listener Administration

Once the listener is configured, the listener can be administered with the Listener Control utility. This section describes some of the common administrative tasks for the listener, including the following topics:

• Starting and Stopping the Listener
• Monitoring Runtime Behavior
• Monitoring Log Files

  See Also: Oracle9i Net Services Reference Guide for a complete listing of all the Listener Control utility commands and the Oracle Net Manager online help contents

Starting and Stopping the Listener

STOP Command

To stop the listener from the command line, enter:

lsnrctl STOP [listener_name]

where listener_name is the name of the listener defined in the listener.ora file. It is not necessary to identify the listener if you are using the default listener, named LISTENER.

START Command

To start the listener from the command line, enter:

lsnrctl START [listener_name]

where listener_name is the name of the listener defined in the listener.ora file. It is not necessary to identify the listener if you are using the default listener, named LISTENER.

In addition to starting the listener, the Listener Control utility verifies connectivity to the listener.

Monitoring Runtime Behavior

The STATUS and SERVICES commands provide information about the listener. When entering these commands, follow the syntax as shown for the STOP and START commands.

STATUS Command

The STATUS command provides basic status information about a listener, including a summary of listener configuration settings, the listening protocol addresses, and a summary of services registered with the listener.

Note: You can also obtain the status of a listener through the Oracle Enterprise Manager Console. See the Oracle Enterprise Manager Administrator's Guide for further information.

The STATUS command generates output with the sections described in Table 12-2.

Table 12-2  Listener Control Utility STATUS Command

Output Section	Description
STATUS of the LISTENER	Specifies the following: Name of the listener Version of listener Start time and up time Tracing level Logging and tracing configuration settings listener.ora file being used Whether a password is set in listener.ora file Whether the listener can respond to queries from an SNMP-based network management system
Listening Endpoints Summary	Lists the protocol addresses the listener is configured to listen on
Services Summary	Displays a summary of the services registered with the listener and the service handlers allocated to each service
Service	Identifies the registered service
Instance	Specifies the name of the instance associated with the service along with its status and number of service handlers associated with the service Status can be one of the following: A READY status means that the instance can accept connections. A BLOCKED status means that the instance cannot accept connections. A READY/SECONDARY status means that this is a secondary instance in an Oracle9i Real Application Clusters primary/secondary configuration and is ready to accept connections. An UNKNOWN status means that the instance is registered statically in the listener.ora file rather than dynamically with service registration. Therefore, the status is non known.

Figure 12-3 shows example output of the STATUS command.

Figure 12-3 Listener Control Utility's STATUS Command Output

Connecting to (DESCRIPTION=(ADDRESS=(PROTOCOL=ipc)(KEY=net)))
STATUS of the LISTENER
------------------------
Alias                     LISTENER
Version                   TNSLSNR for Solaris: Version 9.2.0.2.0 -
Development
Start Date                15-JUL-2002 20:22:00
Uptime                    0 days 0 hr. 5 min. 22 sec
Trace Level               support
Security                  OFF
SNMP                      OFF
Listener Parameter File   /oracle9i/admin/listener.ora
Listener Log File         /oracle9i/network/log/listener.log
Listener Trace File       /oracle9i/network/trace/listener.trc
Listening Endpoints Summary...
  (DESCRIPTION=(ADDRESS=(PROTOCOL=ipc)(KEY=net)))
  (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521)))
  (DESCRIPTION=(ADDRESS=(PROTOCOL=tcps)(HOST=sales-server)(PORT=2484)))
 
Services Summary...
Service "sales.us.acme.com" has 1 instance(s).
  Instance "sales", status READY, has 3 handler(s) for this service...
Service "hr.us.acme.com" has 1 instance(s).
  Instance "hr", status READY, has 2 handler(s) for this service...
The command completed successfully

SERVICES Command

The SERVICES command provides detailed information about the services and instances registered and the service handlers allocated to each instance.

The SERVICES command generates output with the sections described in Table 12-3.

Table 12-3  Listener Control Utility SERVICES Command

Output Section	Description
Service	Identifies the registered service
Instance	Specifies the name of the instance associated with the service
	The status field indicates if the instance is able to accept connections. A READY status means that the instance can accept connections. A BLOCKED status means that the instance cannot accept connections. A READY/SECONDARY status means that this is a secondary instance in an Oracle9i Real Application Cluster primary/secondary configuration and is ready to accept connections. An UNKNOWN status means that the instance is registered statically in the listener.ora file rather than dynamically with service registration. Therefore, the status is non known.
Handlers	Identifies the name of the service handler. Dispatchers are named D000 through D999. Dedicated servers have a name of DEDICATED. This section also identifies the following about the service handler: established: The number of client connections this service handler has established refused: The number of client connections it has refused current: The number of client connections it is handling, that is, its current load max: The maximum number of connections for the service handler, that is, its maximum load state: The state of the handler: - A READY state means that the service handler can accept new connections. - A BLOCKED state means that the service handler cannot accept new connections. Following this, additional information about the service handler displays, such as whether the service handler is a dispatcher, a local dedicated server, or a remote dedicated server on another node.

Figure 12-4 shows example output of the SERVICES command.

Figure 12-4 Listener Control Utility's SERVICES Command Output

Connecting to (DESCRIPTION=(ADDRESS=(PROTOCOL=ipc)(KEY=net)))
Services Summary...
Service "sales.us.acme.com" has 1 instance(s).
  Instance "sales", status READY, has 3 handler(s) for this service...
    Handler(s):
      "DEDICATED" established:0 refused:0 state:ready
         LOCAL SERVER
      "D000" established:0 refused:0 current:0 max:10000 state:ready
         DISPATCHER <machine: sales-server, pid: 1689>
         (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=52414))
      "D001" established:0 refused:0 current:0 max:10000 state:ready
         DISPATCHER <machine: sales-server, pid: 1691>
         (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=52415))
Service "hr.us.acme.com" has 1 instance(s).
  Instance "hr", status READY, has 2 handler(s) for this service...
    Handler(s):
      "DEDICATED" established:0 refused:0 state:ready
         LOCAL SERVER
      "D000" established:0 refused:0 current:0 max:10000 state:ready
         DISPATCHER <machine: sales-server, pid: 11326>
         (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=58361))
The command completed successfully

This output shows that two database services, sales.us.acme.com and hr.us.acme.com, are registered with the listener.

Client connection requests to sales.us.acme.com are handled by two dispatchers named D000 and D001 and one dedicated server. All handlers have a status of ready, indicating that they are ready to receive connections.

Client connection requests to hr.us.acme.com are handled by one dispatcher named D001 and one dedicated server.

Monitoring Log Files

When you notice any of the following conditions, review and monitor the listener log file for the following:

• Long connection establishment times
• Connectivity problems and refusals
• Unexpected shutdown of the listener that could indicate a denial-of-service attack

  See Also: "Analyzing Listener Log Files"