Default Configuration for External Procedures

13.6.1 Default Configuration for External Procedures

An external procedure is a procedure called from another program, written in a different language. An example is a PL/SQL program calling one or more C routines that are required to perform special-purpose processing.

When an application calls an external procedure, Oracle Database starts an external procedure agent named extproc. Using the network connection established by Oracle Database, the application passes the following information to the agent:

DLL or shared library name
External procedure name
Any parameters

The agent then loads the DLL or the shared library, and runs the external procedure and passes back to the application any values returned by the external procedure. The agent must reside on the same computer as the application making the external procedure call.

When you use the default configuration for external procedures, the extproc agent is spawned directly by Oracle Database. There are no configuration changes required for either the listener.ora or tnsnames.ora file. However, you must define the environment variables to be used by external procedures in the extproc.ora file located in the ORACLE_BASE_HOME/hs/admin directory. If the default configuration for external procedures is not used, then the parameters listed in Table 13-6 must be set.

Table 13-6 External Procedures Settings in listener.ora

Oracle Enterprise Manager Cloud Control Field	listener.ora Parameter	Description
Program Name	PROGRAM	The name of the external procedure agent executable. Note: On Microsoft Windows, the executable must reside in the `ORACLE_HOME\bin` directory.
Environment Variables	ENVS	The environment variables to be used by external procedures in the `extproc.ora` file located in the `ORACLE_BASE_HOME/hs/admin` directory. Note: When `extproc.ora` is in use, it precedes the same environment variables of `ENVS` in `listener.ora`. Syntax: `SET` `name=value` Example: `SET EXTPROC_DLLS=ANY` Specify the EXTPROC_DLLS environment variable to restrict the DLLs that the extproc agent is allowed to load. Without the EXTPROC_DLLS environment variable, the extproc agent loads DLLs from the `ORACLE_HOME/lib` directory on UNIX operating systems and the `ORACLE_HOME\bin` directory on Microsoft Windows. Set EXTPROC_DLLS to one of the following values: Colon-separated list of DLLs^Foot 1 Syntax: `"DLL:DLL"` This value allows the extproc agent to load the specified DLLs and the DLLs from the `ORACLE_HOME/lib` directory on UNIX operating systems and the `ORACLE_HOME\bin` directory on Microsoft Windows. You must enter the complete directory path and file name of the DLLs. `ONLY` (Recommended for maximum security)^Foot 1 Syntax: `"ONLY:DLL:DLL"` This value allows the extproc agent to load only the specified DLLs. You must enter the complete directory path and file name of the DLLs. `ANY` Syntax: `"ANY"` Description: This value allows the extproc agent to load any DLL. `ANY` disables DLL checking. Examples: "EXTPROC_DLLS=/home/xyz/mylib.so:/home/abc/urlib.so, LD_LIBRARY_PATH=/private/xpm/lib:/private/mylibs, MYPATH=/usr/ucb:/usr/local/packages,APL_ENV_FILE=/apl/conf/env.txt" "EXTPROC_DLLS=ONLY:/home/xyz/mylib.so:/home/abc/urlib.so, LD_LIBRARY_PATH=/private/xpm/lib:/private/mylibs, MYPATH=/usr/ucb:/usr/local/packages,APL_ENV_FILE=/apl/conf/env.txt" "EXTPROC_DLLS=ANY,LD_LIBRARY_PATH=/private/xpm/lib:/private/mylibs, MYPATH=/usr/ucb:/usr/local/packages,APL_ENV_FILE=/apl/conf/env.txt" Note: If effective user and real user, or effective group and real group are different, then`LD_LIBRARY_PATH`environment setting is ignored.
Oracle Home Directory	ORACLE_HOME	The Oracle home location of the agent.
Oracle System Identifier (SID)	SID_NAME	A system identifier for the external procedure agent by any name. See the examples in Configuring Oracle Net Services for External Procedures for more information about how to work with the external procedure agent spawned by Oracle listener.

^Footnote 1

The DLLs are separated by semi-colons (;) on Microsoft Windows.

Note:

The default configuration for external procedures does not require a network listener to work with Oracle Database and the extproc agent. The extproc agent is spawned directly by Oracle Database and eliminates the risks that the extproc agent might be spawned by Oracle Listener unexpectedly. This default configuration is recommended for maximum security.

You can change the default configuration for external procedures and have the extproc agent spawned by Oracle Listener. To do this, you must perform additional network configuration steps.

Having the extproc agent spawned by Oracle Listener is necessary if you use:

Multi-threaded agent
Oracle Database in MTS mode on Microsoft Windows
The AGENT clause of the LIBRARY specification or the AGENT IN clause of the PROCEDURE specification such that you can redirect external procedures to a different extproc agent.

Configuring Oracle Net Services for External Procedures

13.6.1.1 Configuring Oracle Net Services for External Procedures

You can change the default configuration for external procedures and have the extproc agent spawned by the listener similar to earlier releases of Oracle Database. Here is the process:

1. Configure an existing listener or create a new listener to serve external procedures.

Example 13-1 shows a sample configuration in the listener.ora file.

Example 13-1 listener.ora File with an External Procedure

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.example.com)
      (ORACLE_HOME=/oracle)
      (SID_NAME=sales))
    (SID_DESC=
      (SID_NAME=plsextproc)
      (ORACLE_HOME=/oracle)
      (PROGRAM=extproc)))

2. Add a new entry in tnsnames.ora.

Example 13-2 shows a sample configuration in the tnsnames.ora file.

Example 13-2 tnsnames.ora File with an External Procedure

EXTPROC_CONNECTION_DATA_1=            
 (DESCRIPTION=                     
   (ADDRESS=(PROTOCOL=ipc)(KEY=extproc))                      
   (CONNECT_DATA=
    (SID=plsextproc)))

3. Use AGENT clause of the LIBRARY specification or AGENT IN clause of the PROCEDURE specification such that you can redirect external procedures to a different extproc agent (for example, extproc spawned by Oracle listener).

$ cat test.c

#include <stdlib.h>
int negative(char* db, int n)
{
        return -1*n;
}

char* mygetenv(const char* env)
{
        return getenv(env);
}

$ gcc -shared -fPIC -o test.so test.c

$ cp test.so $ORACLE_HOME/lib

In SQL*PLUS, run:


DROP DATABASE LINK extproclink;
CREATE DATABASE LINK extproclink USING 'extproc_connection_data_1';

CREATE OR REPLACE LIBRARY test1 AS '$ORACLE_HOME/lib/test.so';
/

-- 
-- Use 'AGENT' clause in LIBRARY SPEC
-- 
CREATE OR REPLACE LIBRARY test2 AS '$ORACLE_HOME/lib/test.so' AGENT 'extproclink';
/

-- 
-- Use 'AGENT IN' clause in FUNCTION
-- 
CREATE OR REPLACE FUNCTION ftest1(x VARCHAR2, y BINARY_INTEGER)
RETURN BINARY_INTEGER
AS LANGUAGE C
LIBRARY test1
NAME "negative"
PARAMETERS(x STRING, y INT)
AGENT IN ( x );
/

CREATE OR REPLACE FUNCTION ftest2(x VARCHAR2)
RETURN VARCHAR2
AS LANGUAGE C
LIBRARY test2
NAME "mygetenv";
/

$ select ftest1('extproclink', 123) from dual;

$ select ftest2('LD_LIBRARY_PATH') from dual;

The listener for external procedures should have a user account that does not have general access to the files owned by the oracle user. Specifically, this user should not have permission to read or write to database files or to the Oracle server address space. In addition, this user should have read access to the listener.ora file, but must not have write access to it.

Running the listener with lower privileges also prevents using the Listener Control SET commands to alter the configuration of the listener in the listener.ora file. For this reason, Oracle recommends that you complete listener.ora file configuration before running the listener.

Parent topic: Default Configuration for External Procedures

13.6.1.1.1 Modifying the Default Configuration for External Procedures

To modify the default configuration for external procedures, configure and run a separate or existing listener to serve external procedures. The following procedure describes how to modify the default configuration:

Configure an existing listener to serve external procedures using Oracle Net Configuration Assistant as follows. For most installation types, this listener is named LISTENER.
1. Access the Net Services Administration page in Oracle Enterprise Manager Cloud Control.
2. Select Listeners from the Administer list, and then select the Oracle home that contains the location of the configuration files.
3. Click Go.
  
  The Listeners page appears.
4. Select the existing listener created by Oracle Net Configuration Assistant, and then click Edit.
  
  The Edit Listeners page appears.
5. In the Addresses section, select the protocol address for external procedures, and then click Add.
6. Click the Other Services tab.
7. Select the row representing the service information for external procedures, and then click Add.
Add service information about the extproc agent in the listener.ora file, including the parameters described in Table 13-6.

Parent topic: Configuring Oracle Net Services for External Procedures

13.6.1.1.2 Creating a New Listener to Run External Procedures

To configure and run a separate listener to serve external procedures, create the external procedure entries for a different listener using Oracle Net Configuration Assistant. The following procedure describes how to create a new listener:

Create a listener to exclusively handle external procedures, as follows:
1. Navigate to the Listeners page.
2. Click Create.
  
  The Create Listener page appears.
3. In the Listener Name field, enter a unique listener name, such as LISTENEREXTPROC, in the Listener Name field.
In the Addresses section, configure an IPC protocol address, as follows:
1. Click Add.
  
  The Add Address page appears.
2. From the Protocol list, select IPC.
3. In the Key field, enter a key value of the extproc agent.
4. Click OK.
  
  See Also:
  
  "Configuring Listening Protocol Addresses" for additional information about configuring listener protocol addresses
Add service information about the extproc agent in the listener.ora file, including the parameters described in Table 13-6, as follows:
1. Click the Other Services tab.
2. Click Add.
  
  The Create Other Service page appears.
3. Enter the following values in the fields:
  - extproc in the Program Name field.
  - The Oracle home where the extproc executable resides in the Oracle Home Directory field.
  - System identifier, such as extproc, in the SID field.
4. In the Environment Variables section, click Add Another Row.
5. Enter the EXTPROC_DLLS environment variable in the Name field, and the directory path and file name of the DLLs in the Value field.
6. Click OK.
  
  The Create Listener page appears.
7. Click OK to add the listener.
  
  The listener is added to the Listeners page.
  
  The listener.ora file updates with information for external procedures, as shown in the following output:
```
LISTENEREXTPROC=
 (DESCRIPTION=
  (ADDRESS=
     (PROTOCOL=ipc)(KEY=extproc)))
```
Start the listener for external procedures from a user account with lower privileges than the oracle user.