5
Troubleshooting Oracle Database Cache

This chapter describes error logging, cautions against certain actions, describes some problems you may encounter in your Oracle Database Cache environment and solutions to those problems, and notes restrictions to the software.

Logging Errors

To help you troubleshoot problems in your environment, Oracle Database Cache writes error messages to a log file or an event viewer.

By default, on UNIX, the file specification of the log file is:

$ORACLE_HOME/admin/icache/bdump/wtcme.log

On Windows NT, Oracle Database Cache writes error messages to the Event Viewer. From the Windows NT Start menu, select Programs -> Administrative Tools -> Event Viewer. From the Log menu of the Event Viewer, choose Application. Then, select events named OracleWtcIcache.sid, where sid is the Oracle system identifier (SID) of the cache.

If error messages cannot be written to the event log, errors are written to the log file:

ORACLE_HOME\admin\icache\bdump\wtcme.log

Note that the contents of the log file are always written using the UTF8 character set. If the log file contains non-ASCII characters, you may need to use a text viewer that can display characters in the UTF8 character set.

You can change the level of errors written to the log file and, on UNIX, the name and location of the log file. To make these changes, modify the parameters in the file wtcme.ora or specify a parameter to the wtcme command.

The file wtcme.ora is located in the following directory:

• On UNIX: $ORACLE_HOME/admin/icache/pfile/wtcme.ora

• On Windows NT: ORACLE_HOME\admin\icache\pfile\wtcme.ora

The following table describes the parameters that are specified in the wtcme.ora file:

Parameter	Description
authenticationserver	The tnsname of the origin database. Do not use the command line or edit the file to change this parameter. The tnsname is set during installation.
port	The port number of the listener for Oracle Database Cache. The listener establishes a communication path between Oracle Database Cache on the middle tier and Cache Manager on the client tier. Do not use the command line or edit the file to change this parameter. The port number is set during installation or by using the Configuration Assistant as described in "Using the Configuration Assistant to Reconfigure a Cache". By default, the port number is 51719.
logfile	The full file specification for the log file. By default, the value is set to the following: On UNIX: $ORACLE_HOME/admin/icache/bdump/wtcme.log On Windows NT: ORACLE_HOME\admin\icache\bdump\wtcme.log
loglevel	The level of error messages written to the log file wtcme.log or to the Windows NT Event Viewer. Valid values are: none: No error messages are written to the file. error: Error messages are written to the file. debug: Error messages and other information (such as the start time for the management engine, the TCP port, client connects, client disconnects) are written to the file. trace: Error messages and other information (such as the start time for the management engine, the TCP port, client connects, client disconnects) are written to the file. In addition, all messages sent and received by the Oracle Database Cache management engine are written to the file. Because the volume of messages written to the log file or event viewer is very great, use this value only when you are investigating a problem and the other values do not provide enough information.

The following command specifies a log level of debug:

wtcme loglevel=debug

Important Cautions

The following describes some important information that can help you to prevent problems and fix problems if they occur:

• Oracle Database Cache creates some users on the origin database to facilitate communication between the caches and the origin database. The following users are created:
  • During the installation, the user ORACACHE is created.

  • When you add tables to a cache, Oracle Database Cache adds a user for each schema that contains cached tables. The users are named using the following format:

    ORACACHE$n
    
    

    In the format, n represents an integer between 1 and 1000.

  Do not delete these users from the origin database or change their passwords.

• During installation, Oracle Database Cache creates the following packages in the SYS schema in the origin database:
  • DBMSSIZE

  • DBMS_CACHE_MASTER

  • DBMS_CACHE_MASTER_UTL

  • WTCSINI

  • WTCSYS

  Do not modify or delete these objects.

• You must make sure that Oracle Database Cache and related software is started. See "Starting Oracle Database Cache and Related Software" for more information.

• Do not modify or delete the entries that Oracle Database Cache places in the tnsnames.ora file. If you have modified or deleted the entries, see "Restoring tnsnames.ora Entries" for information on creating the entries again.

• Because Oracle Database Cache uses threads to monitor and maintain statistics about the cache, your application must use OCI in threaded mode. See "Applications Must Be Linked in Multithreaded Mode" for more information.

Port Number Conflicts

If the port number used by Oracle Database Cache is the same number as an existing port, the Configuration Assistant does not return an error during installation. It writes a message to the installation log indicating that the listener is already started.

However, when you attempt to access the cache using the listener (as when clients are routed to the cache), you receive the following error:

ORA-12541 - TNS: no listener

To resolve the problem, edit the listener.ora and tnsnames.ora files and specify a port number that is not used.

Restoring tnsnames.ora Entries

If you modified or deleted the entries that Oracle Database Cache placed in the tnsnames.ora file on the cache node, Oracle Database Cache will not operate correctly. Edit the tnsnames.ora file to match the following entries:

• The Oracle Database Cache management engine communicates with the cache through the ora_icache entry, shown in the following excerpt:

  # Name for the cache.
  ora_icache =
    (DESCRIPTION =
      (ADDRESS_LIST =
        (ADDRESS = (PROTOCOL = IPC)(KEY = <your_dbSid>))
      )
      (CONNECT_DATA = (SERVICE_NAME = <HostName-GlobaldbName>)
      )
    )
  
  

• The Oracle Database Cache management engine communicates with the origin database through the ora_icache_origin entry, shown in the following excerpt:

  # Oracle Database Cache's origin database
  ora_icache_origin =
    (DESCRIPTION =
      (ADDRESS_LIST =
        (ADDRESS = (PROTOCOL = TCP)
                   (HOST = <originHostName>)
                   (PORT = <originPortNumber>))
      )
      (CONNECT_DATA =(SERVICE_NAME = <originServiceName>)
      )
    )
  
  

• The following entry supports external procedures within Oracle Database Cache:

  # Support for external procedures within Oracle Database Cache
  extproc_connection_data =
    (DESCRIPTION =
      (ADDRESS = (PROTOCOL = ipc)(KEY = <your_dbSid>)
      )
      (CONNECT_DATA = (SID = iCache_extproc) (SERVER = DEDICATED)
      )
    )
  
  

• The following entry provides a descriptive name to connect to the cache from the Oracle Enterprise Manager Performance Monitor:

  <HostName-GlobaldbName> =
  (DESCRIPTION =
    (ADDRESS_LIST = 
        (ADDRESS = (PROTOCOL = IPC) (KEY = <your_dbSid>))
        )
        (CONNECT_DATA = (SERVICE_NAME = <HostName-GlobaldbName>)
        )
  )
  
  

• The following entries support Oracle Servlets for Java:

  # Support for mod_ose over normal TCP connections
  inst1_http = 
    (DESCRIPTION =
      (ADDRESS =
        (PROTOCOL = TCP) 
        (HOST = <hostName>) 
        (PORT = 1521)
      )
      (CONNECT_DATA =
        (SERVICE_NAME = MODOSE)
        (SERVER = shared)
        (PRESENTATION = http://admin)
      )
    )
  
  # To support mod_ose over TCP with SSL connections, remove the comments
  # from the following entry:
  #inst1_https = 
  #  (DESCRIPTION =
  #   (ADDRESS =
  #      (PROTOCOL = TCPS) 
  #      (HOST = %s_hostName%) 
  #      (PORT = 2484)
  #    )
  #   (CONNECT_DATA =
  #      (SERVICE_NAME = MODOSE)
  #      (SERVER = shared)
  #      (PRESENTATION = http://admin)
  #   )
  #  )
  

Restoring listener.ora Entries

If you modified or deleted the entries that Oracle Database Cache placed in the listener.ora file on the cache node, Oracle Database Cache will not operate correctly. Edit the listener.ora file to match the following entries:

CONNECT_TIMEOUT_LISTENER = 0
LOGGING_LISTENER = OFF

LISTENER =
  (DESCRIPTION_LIST =
    (DESCRIPTION =                # Local connections
      (ADDRESS_LIST =
        (ADDRESS = (PROTOCOL = IPC)(KEY = <your_dbSid>))
      )
    )
    (DESCRIPTION =                # General TCP connections
      (ADDRESS =
          (PROTOCOL = TCP)(HOST = <hostName>)(PORT = 1521))
    )

# For secure connections over SSL, remove the comment characters 
# from the following entry:
#    (DESCRIPTION =               # Secure TCP connections
#      (ADDRESS =
#          (PROTOCOL = TCPS)(HOST = <hostName>)(PORT = 2484))
#    )

    (DESCRIPTION =                # IIOP connections
      (PROTOCOL_STACK = (PRESENTATION = GIOP) (SESSION = RAW))
      (ADDRESS = (PROTOCOL = TCP)(HOST = <hostName>)(PORT = 2481))
     )
# For secure IIOP connections over SSL, remove the comment characters 
# from the following entry:
#    (DESCRIPTION =                # Secure IIOP connections
#      (PROTOCOL_STACK = (PRESENTATION = GIOP)(SESSION = RAW))
#      (ADDRESS = (PROTOCOL = TCPS)(HOST = <hostName>)(PORT = 2482))
#    )
  )

SID_LIST_LISTENER =
  (SID_LIST =
    (SID_DESC =
      (GLOBAL_DBNAME = <hostName>-<globalDBName>)
      (ORACLE_HOME = <ORACLE_HOME>)
      (SID_NAME = <your_dbSid>)
    )
    (SID_DESC =
      (ORACLE_HOME = <ORACLE_HOME>)
      (SID_NAME = iCache_extproc)
      (PROGRAM = extproc)
    )
  )

Starting Oracle Database Cache and Related Software

To use all features of the Oracle Database Cache product, Oracle Database Cache, the Oracle Database Cache management engine, Oracle Data Gatherer, and TNS Listener must be started.

To use Cache Manager to manage your caches, the Oracle Database Cache management engine must be started. When the management engine is not started on a middle-tier node, Cache Manager cannot access the cache. Cache Manager displays the General page for that cache as dimmed.

If Oracle Data Gatherer and TNS Listener are not started, you will not be able to use Oracle Database Cache or some functionality of the product.

On UNIX systems, if you followed the procedures for automating startup and shutdown in the installation guide, Oracle Database Cache (as well as the Oracle Database Cache management engine, Oracle Data Gatherer, and TNS Listener) is started when your system starts.

On Windows NT systems, Oracle Database Cache, the Oracle Database Cache management engine, and TNS Listener are services that are started automatically when your system starts.

On UNIX, if Oracle Database Cache is stopped, you can restart it, the Oracle Database Cache management engine, Oracle Data Gatherer, and TNS Listener by executing the cachstrt script, which is located in the $ORACLE_HOME/bin directory. Use the following command:

cachstrt

On UNIX, to stop Oracle Database Cache and the TNS Listener, execute the cachshut script, which is located in the $ORACLE_HOME/bin directory:

cachshut

To execute these commands, you must be logged in as the user under which Oracle Database Cache was installed.

On Windows NT, if Oracle Database Cache is stopped, you can restart it by starting the service:

1. From the Windows NT Start menu, select Settings -> Control Panel. Click Services.

2. Select OracleServiceicache and click Start.

On Windows NT, you must start the Oracle Database Cache management engine separately:

1. From the Windows NT Start menu, select Settings -> Control Panel. Click Services.

2. Select OracleWTCiCache and click Start.

To start the Data Gatherer and the TNS Listener, see the following sections.

Starting Oracle Data Gatherer

Oracle Data Gatherer, which manages the collection of statistics for use by Oracle Enterprise Manager components such as DBA Studio, must be started on the middle-tier machine. If it is not, you may receive the following error when you click on the Performance Monitor tab for a cache:

Cannot connect to Data Gatherer for cache. Some performance charts will not be 
available.

On UNIX, use the following command to start Oracle Data Gatherer:

vppcntl -start 

On Windows NT, take these steps to start Oracle Data Gatherer:

1. From the Windows NT Start menu, select Settings -> Control Panel. Click Services.

2. Select Oraclehome_nameDataGatherer and click Start.

Starting the TNS Listener

TNS Listener must be started on the middle-tier node. If it is not, queries are routed to the origin database.

Note that the listener on the middle-tier node is configured to listen for IPC protocol connection requests. The IPC protocol is used by applications that reside on the same node as the listener to communicate with a cache.

On UNIX, use the following command to start the listener:

lsnrctl start listener

On Windows NT, take these steps to start the listener:

1. From the Windows NT Start menu, select Settings -> Control Panel. Click Services.

2. Select Oraclehome_nameTNSListener and click Start.

Applications Must Be Linked in Multithreaded Mode

Oracle Database Cache uses threads to monitor and maintain statistics about the behavior of the cache. As a result, if an application already uses OCI in threaded mode, you do not need to make any changes to the application. If the application is a single-threaded application, you must relink the application using the multithreaded mode.

For example, on UNIX, you use the -lthread option in the link line.

On Windows NT, you link with the msvcrt.lib library.

If the application is not linked in multithreaded mode, Oracle Database Cache may not execute properly and may return errors, such as the following error:

Failed: Register Aggregate Stats Queue