< h1 class="Title">5
Multithreaded Agents< /h1>

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?
• Multithreaded Agent Architecture
• Administering Multithreaded Agents

  Note: Heterogeneous Services supports multi threaded agents, however this functionality may not be available in all Heterogeneous Services based gateways. In addition to the gen eric support for multithreaded agents that Heterogeneous Services provides, multithreaded agents support must be added to the driver. Please refer to your transparent gateway documentation to determine if the gateway you are using is certified to work as a multithre aded agent.

  See Also: Oracle Database Application Developer's Guide - Fundamentals for information on how the extproc agent can be configured to run in MTA mode

Why Use Multithreaded Agents?

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

This section contains the following topics:

• The Challenge of Dedicated Agent Architecture
• The Advantage of Multithreadin g

The Challenge of Dedicated Agent Architecture

By default, a Heter ogeneous 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 starte d under the following conditions:

• The same user session uses t wo different database links to connect to the same non-Oracle system
• Two diffe rent user sessions use the same database link to access the same non-Oracle system.

T his 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-Oracl e 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. Beca use of this, agent processes and open connections can consume a disproportionate amount of system resources without any discernible b enefit.

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 serve r processes.

The Advantage of Multithreading

The Oracle shared server archite cture assumes that even when there are several thousand user sessions currently open, only a small percentage of these connections wi ll be active at any given time. In shared server mode, there is a pool of shared server processes. User sessions connect to dispatche r processes that place the tasks requested by the user sessions on a queue. The tasks are picked up by the first available shared ser ver 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 syst ems. 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 ac tually active at a given moment, using a multithreaded architecture allows for more efficient use of system resources.

Multithreaded Agent Arc hitecture

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 configu re the agent and to shut down the agent.

Each TNS listener that is running on a system list ens 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 t he 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 mul tithreaded agents, each incoming connection request is processed by means of the three different kinds of threads:

• A single monitor thread

  The monitor thread is responsible for the following:

  • Maintaining communication with the listener
  • Monitoring the load on the process
  • Starting and stopping threads when required
< li class="LB1" type="disc">Several dispatcher threads

< /p>

The dispatcher threads are responsible for the following:

• Handling communication with the Oracle server
• Passing task requests on to the task threads
• Several task threads

  The task threads handle requests from the Oracle processes.

The multithreaded agent architecture is illustrated in Figure& nbsp;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 the illustration heter011.gif

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

Note: All requests from a user sessio n 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
• Dispatcher Threads
• Task Threads< /a>

  See Also: Administering Multithreaded Agents for more information on how to start and stop multithreaded agents using the agent control utility

Th e 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:

< li class="LB1" type="disc">It creates the dispatcher and task threads.
• It registers the dispatcher threads it has created with all the listeners that are handling connections to this agent.

  While the dispatcher for this SID is running, the listener does not start a new proces s when it gets an incoming connection. Instead, the listener hands over the connection to this same dispatcher.

• It monitors the other threads and sends load information about the dispatcher threads to all th e listener processes handling connections to this agent.

  This enables the listeners to hand over incoming connections to the least loaded dispatcher.

• It continue s to monitors each of the threads it has created.

Dispatcher Threads

Di spatcher threads perform the following functions:

• They accept incoming connections and task requests from Oracle servers.
• They place incomin g requests on a queue for a task thread to pick up.
• They send results of a req uest back to the server that issued the request.

  Note: Once a user session establishes a connection with a dispatcher, all requests from that user session will go to the same dispatcher until the end of the user session.

Task Threads

Task threads perform the followi ng functions:

• They pick up requests from a queue.
• They perform the necessary operations.
• They place the results on a queue for a dispatcher to pick up.

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-Ora cle 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 informati on from the command line and writes it to a control file.

The following topics are discusse d in this section:

• Agent Contro l Utility (agtctl) Commands
• Using Single-Li ne Command Mode
• Using Shell Mode Commands
• Configuration Parameters for Multithreaded A gent Control

Agent Control Utility (agtctl) Commands

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

Table 5-1 Agent Control Utility Commands

Command	Descri ption
startup	Starts a multithreaded agent
shutdown< /code>	Stops a multithreaded agent
set	Sets a configuration parameter for a multithreaded agent
unset	Causes a parameter to revert to its default value
show	< p class="TB">Displays the value of a configuration parameter
delete	De letes the entry for a particular SID from the control file
exit	Exits shell mode
help	Lists available commands

These commands can be issued in one of two ways:

• You can issue commands from the UNIX (or DOS) shell.

  This mod e is called single-line command mode.

• You can type agtctl and a "AGTCTL>" prompt appears. You then can type commands from within the agtctl shell.

  This mode is called shell mode.

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

Note: 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 dir ectory 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 Heterogen eous Services agent requires an environment variable to be set, or if the ENVS parameter was used when configuring the < code>listener.ora entry for the agent working in dedicated mode, then all required environment variables must be set in the UN IX (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 t he set command to set multithreaded agent configuration parameters.

< h5 class="H4">Syntax 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.

Example

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 agen t. 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.

Example

agtctl startup  extproc  salesDB

Shutting Down a Multithreaded Agent

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

• Normal

  This form of shutdown is the default. It causes agtctl will talk to the agent and ask it to terminate itself gracefu lly. All sessions complete the operations they are currently doing and then shutdown.

• Immediate

  In this form of shutdown, agtctl talks to the agent and tells it to terminate immediately. The agent process exits immediately regardless of the state of current sessions.

• Abort

  In this form of shutdown, agt ctl does not talk to the agent at all. It just issues a system call to kill the agent process.

Syntax

agtctl shutdown [immediate|abort] agent_sid

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

Example

agtctl shutdown immediate salesDB

Examining the Value of Configuration Parameters

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

Syntax

agtctl  show  parameter
agent_sid

parameter is the parameter that you are examining.

Example

agt
ctl  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.

Syntax

agtctl  unset  parameter agent_sid

parameter< /em> is the parameter that you are examining.

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

agtctl  unset  max_dispatchers salesDB

< h4 class="H3">Deleting an Entry for a Specific SID from the Control File

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

Syntax

agtctl  delete  agent_sid

agent_sid is t he SID entry to delete.

Example

agtctl  delete  sales
DB

Req uesting Help

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

Syntax

agtctl help [command]

command is the command whose syntax you want to view.

Example

agtctl help set

Using Shell Mode Commands

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

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

set  agent_sid  agent_sid

All commands issued after this are assumed to be for this p articular 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 messag es, to other than English, as follows:

set  language  language

The commands themselves are the same as those for the single-line com mand 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_addr
ess (address=(protocol=ipc)(key=oraDBsalesDB))

Example: Starting a Multithreaded Agent

< p class="BP">This example starts a multithreaded agent.

startup extproc

Configuration Parameters for Multithreaded Agent Control

The following table lists the config uration parameters for the agent control utility.

Table 5-2 Initialization Parameters for agtctl

Parameter	Description	Default Value
max_dispatchers	Maximum number of dispatchers	1
tcp_dispatchers	Number of dispatchers listening on tcp (the rest are using ipc)	0< /p>
max_task_t hreads	Number of task threads	2
max_sessions	Maximum number of s essions	5
listener_address	Address on which the listener is listening (needed for registration)	(ADDRESS_LIST= (ADDRESS= (PROTOCOL=IPC) (KEY=PNPKEY)) (ADDRESS= (PROTOCOL=IPC) (KEY=oracle_sid)) (ADDRESS= (PROTOCOL=TCP ) (HOST=127.0.0.1) (PORT=1521))) Note: oracle_sid is the SID of the Oracle database.
shutdown_address	Address on which the agent should listen for shutdown messages from agtctl	(ADDRESS= (PROTOCOL=IPC) (KEY= oracle_sid||agent_sid)) Notes: agent_sid is the SID of the multithreaded agen t. || indicates that oracle_sid and agent_sid are concatenated into one string.