External Routines Oracle Database PL/SQL 10g Programming Chapter 12.

External RoutinesExternal RoutinesOracle Database PL/SQL 10g Oracle Database PL/SQL 10g

ProgrammingProgramming

Chapter 12Chapter 12

20062006 Oracle Database PL/SQL 10g Programming Oracle Database PL/SQL 10g Programming

(Chapter 12)(Chapter 12) Page 2

External RoutinesExternal Routines ArchitectureArchitecture Multithreaded Heterogeneous AgentMultithreaded Heterogeneous Agent Oracle Listener ConfigurationOracle Listener Configuration C LibrariesC Libraries Java LibrariesJava Libraries PL/SQL Library WrappersPL/SQL Library Wrappers Troubleshooting Shared LibrariesTroubleshooting Shared Libraries



External RoutinesExternal RoutinesArchitectureArchitecture

External Procedures:External Procedures: Are processes to communicate between external Are processes to communicate between external

programs and the Oracle database.programs and the Oracle database. Are wrapped by PL/SQL stored program units.Are wrapped by PL/SQL stored program units. Use external languages that are callable from the Use external languages that are callable from the

C programming language.C programming language. Use Oracle Net Services to communicate with Use Oracle Net Services to communicate with

external libraries.external libraries. Use Oracle Call Interface (OCI) libraries to map Use Oracle Call Interface (OCI) libraries to map

data types.data types.



External RoutinesExternal RoutinesArchitectureArchitecture

Application callsPL/SQL wrapper

Resolves network?

PL/SQL wrapper forks RPC

Finds library?

Listener spawnsextproc agent

Yes

Yes

Dynamic/shared library

No

No

ORA-28576: Lost RPC connection to external

procedure gate

ORA-06521: PL/SQL: Error mapping function

ORA-28595: Extproc agent: Invalid DLL path

Returnresult

Returnresult

Returnresult



External RoutinesExternal RoutinesMultithreaded Heterogeneous Multithreaded Heterogeneous

AgentAgent Monitoring thread manages Monitoring thread manages

dispatcher threads.dispatcher threads. Dispatcher threads manage task Dispatcher threads manage task

threads.threads. Task threads:Task threads:

Manages external programs.Manages external programs. Exchanges variable values with external Exchanges variable values with external

programs.programs.



External RoutinesExternal RoutinesOracle Listener ConfigurationOracle Listener Configuration

The listener.ora file contains the configuration The listener.ora file contains the configuration information for communicating with extproc information for communicating with extproc programs.programs.

The listener.ora defines:The listener.ora defines: EXTPROC_DLLS to enable shared external libraries.EXTPROC_DLLS to enable shared external libraries. $LD_LIBRARY_PATH for the extproc agent.$LD_LIBRARY_PATH for the extproc agent. $PATH for the extproc agent.$PATH for the extproc agent. $APL_ENV_FILE for required environment variables that $APL_ENV_FILE for required environment variables that

support the extproc agent.support the extproc agent. The IPC and TCP protocols should be run on separate The IPC and TCP protocols should be run on separate

listeners.listeners.




CALLOUT_LISTENER =CALLOUT_LISTENER = (DESCRIPTION_LIST =(DESCRIPTION_LIST = (DESCRIPTION =(DESCRIPTION = (ADDRESS_LIST =(ADDRESS_LIST = (ADDRESS = (ADDRESS = (PROTOCOL = IPC)(PROTOCOL = IPC) (KEY = extproc)(KEY = extproc) )) )) )) ))




SID_LIST_CALLOUT_LISTENER =SID_LIST_CALLOUT_LISTENER = (SID_LIST =(SID_LIST = (SID_DESC =(SID_DESC = (SID_NAME = PLSExtProc)(SID_NAME = PLSExtProc) (ORACLE_HOME = <(ORACLE_HOME = <oracle_home_directoryoracle_home_directory>)>) (PROGRAM = extproc)(PROGRAM = extproc) (ENV = "EXTPROC_DLLS=ONLY:(ENV = "EXTPROC_DLLS=ONLY: <<oracle_homeoracle_home>/<>/<custom_librarycustom_library>/writestr1.so,>/writestr1.so, LD_LIBRARY_PATH=<LD_LIBRARY_PATH=<oracle_homeoracle_home>/lib")>/lib") )) ))



External RoutinesExternal Routines C Library: Sample Source C Library: Sample Source

/* Include standard IO. *//* Include standard IO. */#include <stdio.h>#include <stdio.h>/* Declare a writestr function. *//* Declare a writestr function. */void writestr1(char *path, char *message) {void writestr1(char *path, char *message) { /* Declare a FILE variable. *//* Declare a FILE variable. */ FILE *file_name;FILE *file_name; /* Open the File. *//* Open the File. */ file_name = fopen(path,"w");file_name = fopen(path,"w"); /* Write to file the message received. *//* Write to file the message received. */ fprintf(file_name,"%s\n",message);fprintf(file_name,"%s\n",message); /* Close the file. *//* Close the file. */ fclose(file_name); }fclose(file_name); }



External RoutinesExternal RoutinesC Library: CompilationC Library: Compilation

Unix C Compiler that supports the –G optionUnix C Compiler that supports the –G optioncc –G –o writestr1.so writestr1.ccc –G –o writestr1.so writestr1.c

Unix C Compiler that supports the –shared optionUnix C Compiler that supports the –shared optioncc –shared –o writestr1.so writestr1.ccc –shared –o writestr1.so writestr1.c

ororgcc –shared –o writestr1.so writestr1.cgcc –shared –o writestr1.so writestr1.c



External RoutinesExternal Routines C Library: Defining Library C Library: Defining Library

CREATE [OR REPLACE] LIBRARY <CREATE [OR REPLACE] LIBRARY <library_namelibrary_name> {AS | IS}> {AS | IS}'<'<oracle_homeoracle_home>/<>/<custom_librarycustom_library>/<>/<file_namefile_name>.<>.<file_extfile_ext>';>';



External RoutinesExternal Routines Java Library: I/O Java Library: I/O

PermissionsPermissions-- Grant Java permission to file I/O against a file.-- Grant Java permission to file I/O against a file.DBMS_JAVA.GRANT_PERMISSION('PLSQL'DBMS_JAVA.GRANT_PERMISSION('PLSQL' 'SYS:java.io.FilePermission''SYS:java.io.FilePermission' '/tmp/file.txt''/tmp/file.txt' 'read');'read');



External RoutinesExternal Routines Java Library: Loading Class Java Library: Loading Class

FileFile Load the Java class file into the database:Load the Java class file into the database:

$ loadjava –r –f –o –user plsql/plsql ReadFile1.class$ loadjava –r –f –o –user plsql/plsql ReadFile1.class



External RoutinesExternal RoutinesPL/SQL Library Wrapper: C PL/SQL Library Wrapper: C

LanguageLanguageCREATE [OR REPLACE] PROCEDURE write_stringCREATE [OR REPLACE] PROCEDURE write_string(path VARCHAR2(path VARCHAR2,message VARCHAR2) AS EXTERNAL,message VARCHAR2) AS EXTERNALLIBRARY library_write_stringLIBRARY library_write_stringNAME NAME "writestr ""writestr "PARAMETERSPARAMETERS(path STRING(path STRING,message STRING);,message STRING);//



External RoutinesExternal RoutinesPL/SQL Library Wrapper: Java PL/SQL Library Wrapper: Java

LanguageLanguageCREATE [OR REPLACE] PROCEDURE read_stringCREATE [OR REPLACE] PROCEDURE read_string(file IN VARCHAR2)(file IN VARCHAR2)RETURN VARCHAR2 ISRETURN VARCHAR2 ISLANGUAGE JAVALANGUAGE JAVANAME 'ReadFile.readString(java.lang.String) return String';NAME 'ReadFile.readString(java.lang.String) return String';//



External RoutinesExternal RoutinesTroubleshooting Shared LibrariesTroubleshooting Shared Libraries

Listener Listener ENVENV parameter is incorrect parameter is incorrect when an ORA-06520 is raised:when an ORA-06520 is raised: Incorrect synchronization of file path, Incorrect synchronization of file path, EXTPROC_DLLSEXTPROC_DLLS value, and PL/SQL value, and PL/SQL wrapper NAME parameter.wrapper NAME parameter.

Incorrect value for Incorrect value for EXTPROC_DLLSEXTPROC_DLLS or or LD_LIBRARY_PATHLD_LIBRARY_PATH environment environment variables.variables.



External RoutinesExternal RoutinesTroubleshooting Shared LibrariesTroubleshooting Shared Libraries

Listener Listener KEYKEY parameter is incorrect or parameter is incorrect or inconsistent between the inconsistent between the listener.oralistener.ora and and tnsnames.oratnsnames.ora files when an files when an ORA-28576ORA-28576 is raised. is raised.

An An ORA-28576ORA-28576 is also raised when the extproc is also raised when the extproc listener is shutdown or not running.listener is shutdown or not running.

An An ORA-28576ORA-28576 is also raised when the extproc is also raised when the extproc listener for IPC is not separated from the listener listener for IPC is not separated from the listener running for TCP communication.running for TCP communication.

Other errors occur when the name in the PL/SQL Other errors occur when the name in the PL/SQL wrapper fails to resolve to a library file name.wrapper fails to resolve to a library file name.



SummarySummary ArchitectureArchitecture Multithreaded Heterogeneous AgentMultithreaded Heterogeneous Agent Oracle Listener ConfigurationOracle Listener Configuration C LibrariesC Libraries Java LibrariesJava Libraries PL/SQL Library WrappersPL/SQL Library Wrappers Troubleshooting Shared LibrariesTroubleshooting Shared Libraries

External Routines Oracle Database PL/SQL 10g Programming Chapter 12.

Documents

Transcript of External Routines Oracle Database PL/SQL 10g Programming Chapter 12.