Overview of The Call Specification for External Procedures

Overview of The Call Specification for External Procedures

You publish external procedures through call specifications, which provide a superset of the AS EXTERNAL function through the AS LANGUAGE clause. AS LANGUAGE call specifications allow the publishing of external C procedures, but also Java class methods.

Note: To support legacy applications, call specifications also allow you to publish with the AS EXTERNAL clause. For new application development, however, using the AS LANGUAGE clause is recommended.

In general, call specifications enable:

■Dispatching the appropriate C or Java target procedure

■Datatype conversions

■Parameter mode mappings

■Automatic memory allocation and cleanup

■Purity constraints to be specified, where necessary, for packaged functions called from SQL.

■Calling Java methods or C procedures from database triggers

■Location flexibility: you can put AS LANGUAGE call specifications in package or type specifications, or package (or type) bodies to optimize performance and hide implementation details

To use an already-existing program as an external procedure, load, publish, and then call it.

Loading External Procedures

To make your external C procedures or Java methods available to PL/SQL, you must first load them. The manner of doing this depends upon whether the procedure is written in C or Java.

8-4 Oracle Database Application Developer's Guide - Fundamentals

Loading External Procedures

Loading Java Class Methods

One way to load Java programs is to use the CREATE JAVA statement, which you can execute interactively from SQL*Plus. When implicitly invoked by the CREATE JAVA statement, the Java Virtual Machine (JVM)] library manager loads Java binaries (.class files) and resources from local BFILEs or LOB columns into RDBMS libunits.

Suppose a compiled Java class is stored in the following operating system file:

/home/java/bin/Agent.class

Creating a class libunit in schema scott from file Agent.class requires two steps: First, create a directory object on the server's file system. The name of the directory object is an alias for the directory path leading to Agent.class.

To create the directory object, you must grant user scott the CREATE ANY DIRECTORY privilege, then execute the CREATE DIRECTORY statement, as follows:

CONNECT System/Manager

GRANT CREATE ANY DIRECTORY TO Scott IDENTIFIED BY Tiger;

CONNECT Scott/Tiger

CREATE DIRECTORY Bfile_dir AS '/home/java/bin';

You are ready to create the class libunit, as follows:

CREATE JAVA CLASS USING BFILE (Bfile_dir, 'Agent.class');

The name of the libunit is derived from the name of the class.

Alternatively, you can use the command-line utility LoadJava. This uploads Java binaries and resources into a system-generated database table, then uses the CREATE JAVA statement to load the Java files into RDBMS libunits. You can upload Java files from file systems, Java IDEs, intranets, or the Internet.

Loading External C Procedures

In order to set up your database configuration to use external procedures that are written in C, or can be called from C applications, you and your database administrator must take the following steps:

Calling External Procedures 8-5

Loading External Procedures

Note:

■This feature is available only on platforms that support dynamically linked libraries (DLLs) or dynamically loadable shared libraries such as Solaris .so libraries.

■The external procedure agent can call procedures in any library that complies with the calling standard used. The supported calling standard is C. See "CALLING STANDARD" on page 8-12 for more information on the calling standard sub clause used with external procedures in PL/SQL.

Step 1 Set Up the Environment

Your database administrator must perform the following tasks to configure your database to use external procedures that are written in C, or can be called from C applications:

■Set configuration parameters for the agent, named extproc by default, in the configuration files tnsnames.ora and listener.ora. This establishes the connection for the external procedure agent when the database is started.

■Start a listener process exclusively for external procedures.

The Listener sets a few required environment variables (such as ORACLE_HOME, ORACLE_SID, and LD_LIBRARY_PATH) for the external procedure agent. It can also define specific environment variables in the ENVS section of its listener.ora entry, and these variables are passed to the agent process. Otherwise, it provides the agent with a "clean" environment. The environment variables set for the agent are independent of those set for the client and server. Therefore, external procedures, which run in the agent process, cannot read environment variables set for the client or server processes.

Note: It is possible for you to set and read environment variables themselves by using the standard C procedures setenv() and getenv(), respectively. Environment variables, set this way, are specific to the agent process, which means that they can be read by all functions executed in that process, but not by any other process running on the same host.

■Determine whether the agent for your external procedure will run in dedicated mode (the default mode) or multithreaded mode. In dedicated mode, one

8-6 Oracle Database Application Developer's Guide - Fundamentals

Loading External Procedures

"dedicated" agent is launched for each user. In multithreaded mode, a single multithreaded agent is launched. The multithreaded agent handles calls using different threads for different users. In a configuration where many users will call the external procedures, using a multithreaded agent is recommended to conserve system resources.

If the agent will run in dedicated mode, additional configuration of the agent process is not necessary.

If the agent will run in multithreaded mode, your database administrator must configure the database system to start the agent in multithreaded mode (as a multithreaded agent). This is done using the agent control utility agtctl. For example, start the agent using the agent control utility startup command:

agtctl startup extproc agent_sid

where agent_sid is the system identifier which this agent will service. An entry for this system identifier is typically added as an entry in the file tnsnames.ora. Details on the agent control utility are in the Oracle Database Heterogeneous Connectivity Administrator's Guide.

Note:

■If you use a multithreaded agent, the library you call must be thread safe—to avoid errors such as a corrupt call stack.

■The database server, the agent process, and the listener process that spawns the agent process must all reside on the same host.

■By default, the agent process runs on the same database instance as your main application. In situations where reliability is critical, you might want to run the agent process for the external procedure on a separate database instance (still on the same host), so that any problems in the agent do not affect the primary database server. To do so, specify the separate database instance using a database link.

Figure 8–1 illustrates the architecture of the multithreaded external procedure agent. User sessions 1 and 2 issue requests for callouts to functions in some DLLs. These requests get serviced through heterogeneous services to the multithreaded extproc agent. These requests get handled by the agent's dispatcher threads, which then pass them on to the task threads. The task thread that is actually handling a request is responsible for loading the respective DLL and calling the function therein.

Calling External Procedures 8-7

Loading External Procedures

■All requests from a user session get handled by the same dispatcher thread. For example, dispatcher 1 handles communication with user session 1, and dispatcher 2 handles communication with user session 2. This is the case for the lifetime of the session.

■The individual requests can, however, be serviced by different task threads. For example, task thread 1 could handle the request from user session 1 at one time, and handle the request from user session 2 at another time.

Figure 8–1 Multithreaded External Procedure Agent Architecture

8-8 Oracle Database Application Developer's Guide - Fundamentals

Loading External Procedures

See Also:

■Oracle Database Heterogeneous Connectivity Administrator's Guide for details on configuring the agent process for the external procedure to use multithreaded mode, architecture, and for additional details on multithreaded agents

■Oracle Database Administrator's Guide. for details on managing processes for external procedures

Step 2 Identify the DLL

In this context, a DLL is any dynamically loadable operating-system file that stores external procedures.

For security reasons, your DBA controls access to the DLL. Using the CREATE LIBRARY statement, the DBA creates a schema object called an alias library, which represents the DLL. Then, if you are an authorized user, the DBA grants you EXECUTE privileges on the alias library. Alternatively, the DBA may grant you CREATE ANY LIBRARY privileges, in which case you can create your own alias libraries using the following syntax:

CREATE LIBRARY [schema_name.]library_name

{IS | AS} 'file_path' [AGENT 'agent_link'];

It is recommended that you specify the full path to the DLL, rather than just the DLL name. In the following example, you create alias library c_utils, which represents DLL utils.so:

CREATE LIBRARY C_utils AS '/DLLs/utils.so';

To allow flexibility in specifying the DLLs, you can specify the root part of the path as an environment variable using the notation ${VAR_NAME}, and set up that variable in the ENVS section of the listener.ora entry.

In the following example, the agent specified by the name agent_link is used to run any external procedure in the library C_Utils. The environment variable EP_ LIB_HOME is expanded by the agent to the appropriate path for that instance, such as /usr/bin/dll. Variable EP_LIB_HOME must be set in the file listener.ora, for the agent to be able to access it.

create or replace database link agent_link using 'agent_tns_alias'; create or replace library C_utils is

'${EP_LIB_HOME}/utils.so' agent 'agent_link';

Calling External Procedures 8-9