Skip Headers

Oracle® Database Heterogeneous Connectivity Administrator's Guide
10g Release 1 (10.1)

Part Number B10764-01
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Index
Go to Master Index
Master Index
Go to Feedback page

Go to previous page
Go to next page
View PDF

Multithreaded Agents

This chapter explains what multithreaded agents are, how they contribute to the overall efficiency of a distributed database system, and how to administer multithreaded agents.

This chapter contains the following sections:

Why Use Multithreaded Agents?

This section explains how multithreaded agents contribute to the overall efficiency of Heterogeneous Services and Oracle Transparent Gateways.

This section contains the following topics:

The Challenge of Dedicated Agent Architecture

By default, a Heterogeneous Services agent is started up for each user session. When a user session attempts to access a non-Oracle system by means of a particular database link, an agent process is started up that is exclusively dedicated to that user session and that database link. The agent process terminates only when the user session ends or when the database link is closed. Separate agent processes are started under the following conditions:

This architecture has the disadvantage of potentially consuming an unnecessarily large amount of system resources.

For example, suppose that there are several thousand user sessions simultaneously accessing the same non-Oracle system. Because an agent process is started for each one of them, there are several thousand agent processes running concurrently. The agent processes are all running regardless of whether each individual agent process is actually active at the moment or not. Because of this, agent processes and open connections can consume a disproportionate amount of system resources without any discernible benefit.

In the case of connections to the Oracle database server, this problem is addressed by starting the server in shared server mode. Shared server mode allows database connections to be shared by a small number of server processes.

The Advantage of Multithreading

The Oracle shared server architecture assumes that even when there are several thousand user sessions currently open, only a small percentage of these connections will be active at any given time. In shared server mode, there is a pool of shared server processes. User sessions connect to dispatcher processes that place the tasks requested by the user sessions on a queue. The tasks are picked up by the first available shared server processes. The number of shared server processes is usually considerably less that the number of user sessions.

Multithreaded Heterogeneous Services agents provide similar functionality for connections to non-Oracle systems. The multithreaded agent architecture uses a pool of shared agent threads. The tasks requested by the user sessions are put on a queue and are picked up by the first available multithreaded agent thread. Because only a small percentage of user connections are actually active at a given moment, using a multithreaded architecture allows for more efficient use of system resources.

Multithreaded Agent Architecture

Multithreaded agents must be prestarted on a one for each system identifier (SID) basis. This is done using the agent control utility agtctl. This utility is also used to configure the agent and to shut down the agent.

Each TNS listener that is running on a system listens for incoming connection requests for a set of SIDs. If the SID in an incoming Oracle Net connect string is one of the SIDs that the listener is listening for, then that listener will process the connection. Further, if a multithreaded agent has been started for the SID, then the listener will pass the request to that agent.

In the architecture for multithreaded agents, each incoming connection request is processed by means of the three different kinds of threads:

The multithreaded agent architecture is illustrated in Figure 5-1 where each request issued by a user session is represented in by a separate type of arrow. There is no representation of the monitor thread in this illustration, because that thread is created once when the multithreaded agent is started and it creates and monitors the other threads. Typically there are many more task threads than dispatcher threads.

Figure 5-1 Multithreaded Agent Architecture

Text description of heter011.gif follows

Text description of the illustration heter011.gif

These three thread types roughly correspond to the Oracle multithreaded server's PMON, dispatcher and shared server processes respectively.


All requests from a user session go through the same dispatcher thread, but can be serviced by different task threads. It is also possible for several task threads to use the same connection to the non-Oracle system.

Each type of thread is discussed in more detail in the following sections:

The Monitor Thread

When a multithreaded agent is started for a SID by the agent control utility, the monitor thread is created. The monitor thread performs the following functions:

Dispatcher Threads

Dispatcher threads perform the following functions:

Task Threads

Task threads perform the following functions:

Administering Multithreaded Agents

As discussed earlier, multithreaded Heterogeneous Services agents must be prestarted on a one for each system identifier (SID) basis before any attempt is made to connect to the non-Oracle system. Any agent not spawned in this fashion will not function in multithreaded mode, and must be set up as described in "Setting Up Access to Non-Oracle Systems".

A multithreaded agent is started, stopped, and configured by an agent control utility called agtctl, which works much like lsnrctl. However, unlike lsnrctl, which reads a configuration file (listener.ora), agtctl takes configuration information from the command line and writes it to a control file.

The following topics are discussed in this section:

Agent Control Utility (agtctl) Commands

You start and stop agtctl, and create and maintain its control file, using the commands shown in Table 5-1.

Table 5-1 Agent Control Utility Commands
Command Description


Starts a multithreaded agent


Stops a multithreaded agent


Sets a configuration parameter for a multithreaded agent


Causes a parameter to revert to its default value


Displays the value of a configuration parameter


Deletes the entry for a particular SID from the control file


Exits shell mode


Lists available commands

These commands can be issued in one of two ways:

The syntax and parameters for agtctl commands vary depending upon the mode in which they are issued.

  • All commands are case sensitive.
  • The agent control utility puts its control file in either the directory pointed to by the environment variable AGTCTL_ADMIN or in the directory pointed to by the environment variable TNS_ADMIN. Ensure that at least one of these environment variables is set and that it points to a directory that the agent has access to
  • If the Heterogeneous Services agent requires an environment variable to be set, or if the ENVS parameter was used when configuring the listener.ora entry for the agent working in dedicated mode, then all required environment variables must be set in the UNIX (or DOS) shell which runs the agtctl utility.

Using Single-Line Command Mode

This section describes the use of agtctl commands. They are presented in single-line command mode.

Setting Configuration Parameters for a Multithreaded Agent

You should set the configuration parameters for a multithreaded agent before you start the agent. They determine how the agent will be configured. If a configuration parameter is not specifically set, a default value is used. Configuration parameters and their default values are shown in Table 5-2.

Use the set command to set multithreaded agent configuration parameters.

agtctl set  parameter  parameter_value  agent_sid

parameter is the parameter that you are setting.
parameter_value is the value being assigned to the parameter.
agent_sid is the SID that this agent will service. Must be specified for single-line command mode.
agtctl  set  max_dispatchers 5 salesDB

Starting a Multithreaded Agent

Use the startup command to start an agent in multithreaded mode.

agtctl startup  agent_name  agent_sid

agent_name is the name of the agent. For example, extproc is an agent name.
agent_sid is the SID that this agent will service. Must be specified for single-line command mode.
agtctl startup  extproc  salesDB

Shutting Down a Multithreaded Agent

Use the shutdown command to stop a multithreaded agent. There are three forms of shutdown.

agtctl shutdown [immediate|abort] agent_sid

agent_sid is the SID which this agent will service. Must be specified for single-line command mode.

agtctl shutdown immediate salesDB

Examining the Value of Configuration Parameters

To examine the value of a configuration parameter use the show command.

agtctl  show  parameter agent_sid

parameter is the parameter that you are examining.

agtctl  show  max_dispatchers salesDB

Resetting a Configuration Parameter to Its Default Value

You can reset a configuration parameter to its default value using the unset command.

agtctl  unset  parameter agent_sid

parameter is the parameter that you are examining.
agent_sid is the SID which this agent will service. Must be specified for single-line command mode.
agtctl  unset  max_dispatchers salesDB

Deleting an Entry for a Specific SID from the Control File

The delete command deletes the entry for the specified SID from the control file.

agtctl  delete  agent_sid

agent_sid is the SID entry to delete.

agtctl  delete  salesDB

Requesting Help

Use the help command to view a list of available commands for agtctl, or to see the syntax for a particular command.

agtctl help [command]

command is the command whose syntax you want to view.

agtctl help set

Using Shell Mode Commands

In shell mode, you start agtctl by typing agtctl whereupon you will see an "AGTCTL>" prompt. Thereafter, since you are issuing commands from within the agtctl shell, you do not prefix the command string with the word agtctl.

Next, set the name of the agent SID that you are working with by entering the following:

set  agent_sid  agent_sid

All commands issued after this are assumed to be for this particular SID until the agent_sid value is changed. Unlike single-line command mode, you do not specify agent_sid in the command string.

You can optionally set the language for error messages, to other than English, as follows:

set  language  language

The commands themselves are the same as those for the single-line command mode. To exit shell mode, type exit.

The following are examples of shell mode commands.

Example: Setting a Configuration Parameter

This example sets a new value for the shutdown_address configuration parameter.

set shutdown_address (address=(protocol=ipc)(key=oraDBsalesDB))

Example: Starting a Multithreaded Agent

This example starts a multithreaded agent.

startup extproc

Configuration Parameters for Multithreaded Agent Control

The following table lists the configuration parameters for the agent control utility.

Table 5-2 Initialization Parameters for agtctl
Parameter Description Default Value


Maximum number of dispatchers



Number of dispatchers listening on tcp (the rest are using ipc)



Number of task threads



Maximum number of sessions



Address on which the listener is listening (needed for registration)


Note: oracle_sid is the SID of the Oracle database.


Address on which the agent should listen for shutdown messages from agtctl



  • agent_sid is the SID of the multithreaded agent.
  • || indicates that oracle_sid and agent_sid are concatenated into one string.