Oracle PLSQL Language- P23

Chia sẻ: Thanh Cong | Ngày: | Loại File: PDF | Số trang:50

Thêm vào BST

Báo xấu

52
lượt xem 5
download

Download Vui lòng tải xuống để xem tài liệu đầy đủ

Tham khảo tài liệu 'oracle plsql language- p23', công nghệ thông tin, cơ sở dữ liệu phục vụ nhu cầu học tập, nghiên cứu và làm việc hiệu quả

Chủ đề:

Bình luận(0) Đăng nhập để gửi bình luận!

Lưu

Nội dung Text: Oracle PLSQL Language- P23

FOR EACH ROW DECLARE l_file_name images.file_name%TYPE; l_directory VARCHAR2(30); BEGIN /* Determine the directory name */ DBMS_LOB.FILEGETNAME (file_loc => :NEW.image_file, dir_alias => l_directory, filename => l_file_name); /* This will fail with DUP_VAL_ON_INDEX if the images table || already contains a record with the new image_id. */ INSERT INTO images VALUES (:NEW.image_id, l_file_name, :NEW.file_type, :NEW.bytes); IF :NEW.keywords IS NOT NULL THEN DECLARE /* Note: apparent bug prevents use of :NEW. keywords.LAST. || The workaround is to store :NEW.keywords as a local || variable (in this case keywords_holder.) */ keywords_holder Keyword_tab_t := :NEW.keywords; BEGIN FOR the_keyword IN 1..keywords_holder.LAST LOOP INSERT INTO keywords VALUES (:NEW.image_id, keywords_holder (the_keyword)); END LOOP; END; END IF; END; And finally, we can demonstrate how an insert would be made using the object view: INSERT INTO images_v VALUES (Image_t (1002, BFILENAME('WEBPIX','abc.gif'), 'GIF', 1024, Keyword_tab_t('ALPHABET', 'LETTERS'))); Appendix C, Built-In Packages, contains information about these built-in packages. Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
Previous: 20.7 Object Oracle PL/SQL Next: 21. External Views Housekeeping Programming, 2nd Edition Procedures 20.7 Object Views Book Index 21. External Procedures Housekeeping The Oracle Library Navigation Copyright (c) 2000 O'Reilly & Associates. All rights reserved. Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
Previous: 20.8 Postscript: Chapter 21 Next: 21.2 Steps in Using the BFILE Datatype Creating an External Procedure 21. External Procedures Contents: Introduction to External Procedures Steps in Creating an External Procedure Syntax for External Procedures Mapping Parameters OCI Service Routines External Procedure Housekeeping Examples I've lost count of how many times I've heard the question "Can I call whatever from within Oracle?" Typically, whatever is a program that interacts with the external environment: sending email, polling or controlling hardware, or invoking the C library functions that PL/SQL lacks. Until very recently, the standard answer was "No, you can't do that directly, but you can use a database pipe and write a daemon that responds to requests on the pipe." An early paper on this approach[1] describes pipes as an alternative to an even more primitive approach: using a temporary table as a sort of "bulletin board" for interprocess communication.[2] [1] See Dan Bikle, "Inter-Application Communication Using Oracle7 Database Pipes," Select Vol. 1, No. 2, Winter 93/94, p. 34. [2] The original paper did not present a true UNIX daemon (which has a specific definition to UNIX and C programmers), but rather discussed the generic idea of a continuously running process. Temporary tables have serious limitations for this use, and even database pipe-based daemons have their shortcomings. Packing and unpacking the contents of the pipe is a challenge; the daemon typically execute in a separate Oracle session (and thus can't participate in a transaction), and the solution is inherently single-threaded. Moreover, with the pipe solution, it's difficult to get return values back from the daemon to the caller. What we need from Oracle is a fast, reliable way of calling out to operating system commands or functions from within PL/SQL. Better yet, Oracle Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
should allow external routines to serve as user-defined functions so that you can use them in SQL statements. Enter external procedures. This long-awaited Oracle feature allows you to call anything that you can compile into the native "shared library" format of the operating system. Yes, the external procedures features is reliable; yes, it's multi-threaded; yes, communication is bidirectional; and yes, you can use external procedures as user-defined functions in SQL. Under UNIX, a shared library is a shared object or .so file; under Windows NT, it's a DLL (dynamically linked library). You can write the external routine in any language you wish, as long as your compiler and linker will generate the appropriate shared library format that is callable from C. In Oracle 8.0, however, C will be the most common language for external procedures, since all of Oracle's support libraries are written in C. Curiously, Oracle has named this feature external "procedures," although the external routines you invoke are, technically speaking, C functions. (There is no such thing as a procedure in C.) If the C function returns a value, you map it to a PL/SQL function; if it returns no value, you map it to a PL/SQL procedure. This chapter presents a few examples of external procedures (and functions). In addition, we review the preconditions you must establish before they will work, and present the syntax for creating and using this new feature. So, the next time you hear the question about calling whatever, you can answer, "You bet!...in Oracle8." This chapter does not discuss "distributed external procedures," which are a way of accessing non- Oracle data sources from an Oracle server. Despite the name, these procedures are not closely related to external procedures. Neither do we discuss at length the programming techniques that allow your 3GL code to call back to Oracle (we'll leave that to the books on programming C language access to Oracle). But we do include some samples that you can use right away. 21.1 Introduction to External Procedures How do external procedures work? How can I build my own? What are their advantages and disadvantages? Before answering in detail, let's take a look at a quick example. 21.1.1 Example: Determining Free Disk Space on Windows NT Here is an external procedure that will discover the amount of free space on a given disk drive. This example is just to get you going. We won't try to explain all the details at this point. This example was designed for Windows NT 4.0, but the idea can be applied to any operating system that meets the requirements for external procedures. In this case, we simply make a call to the appropriate function in the Windows kernel, rather than writing our own DLL. Windows NT's kernel, kernel32.dll, contains a routine called GetDiskFreeSpaceA, which accepts a drive letter as an input parameter and returns four statistics about the drive. When we register the routine with PL/SQL, we will provide mappings for each of these parameters to a PL/SQL parameter. Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
Then, when we invoke the external procedure from a PL/SQL program, we'll use these statistics to compute the free disk space. First, we need to define a "library" to tell Oracle where the DLL lives: /* Filename on companion disk: nt_space.sql */ CREATE OR REPLACE LIBRARY nt_kernel AS 'c:\winnt\system32\kernel32.dll'; We'll create a package called disk_util that will contain our function, which we will call get_disk_free_space as shown here: CREATE OR REPLACE PACKAGE disk_util AS FUNCTION get_disk_free_space (root_path IN VARCHAR2, sectors_per_cluster OUT PLS_INTEGER, bytes_per_sector OUT PLS_INTEGER, number_of_free_clusters OUT PLS_INTEGER, total_number_of_clusters OUT PLS_INTEGER) RETURN PLS_INTEGER; PRAGMA RESTRICT_REFERENCES (get_disk_free_space, WNPS, RNPS, WNDS, RNDS); END disk_util; All the magic is in the package body, which uses the EXTERNAL clause rather than a BEGIN..END block. This clause is where we define the interface between PL/SQL and the external routine: CREATE OR REPLACE PACKAGE BODY disk_util AS FUNCTION get_disk_free_space (root_path IN VARCHAR2, sectors_per_cluster OUT PLS_INTEGER, bytes_per_sector OUT PLS_INTEGER, number_of_free_clusters OUT pls_integer, total_number_of_clusters OUT PLS_INTEGER) RETURN PLS_INTEGER IS EXTERNAL LIBRARY nt_kernel -- our library (defined previously) NAME "GetDiskFreeSpaceA" -- name of function in kernel32.dll LANGUAGE C -- external routine is written in C Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
CALLING STANDARD PASCAL -- uses Pascal parameter convention PARAMETERS -- map PL/SQL to C parameters by -- position (root_path STRING, sectors_per_cluster BY REFERENCE LONG, bytes_per_sector BY REFERENCE LONG, number_of_free_clusters BY REFERENCE LONG, total_number_of_clusters BY REFERENCE LONG, RETURN LONG); -- "return code" indicating success or failure END disk_util; Assuming that the DBA has set up the environment to support external procedures (see Section 21.2.1, "Step 1: Set Up the Listener" later in this chapter), we can make an easy call to compute free disk space on the C: drive: SET SERVEROUTPUT ON SIZE 100000 DECLARE lroot_path VARCHAR2(3) := 'C:\'; -- look at C drive lsectors_per_cluster PLS_INTEGER; lbytes_per_sector PLS_INTEGER; lnumber_of_free_clusters PLS_INTEGER; ltotal_number_of_clusters PLS_INTEGER; return_code PLS_INTEGER; free_meg REAL; BEGIN /* Call the external procedure. We ignore the return code || in this simple example. */ return_code := disk_util.get_disk_free_space (lroot_path, lsectors_per_cluster, lbytes_per_sector, lnumber_of_free_clusters, ltotal_number_of_clusters); /* Using the drive statistics that are returned from the || external procedure, compute the amount of free disk space. || Remember Megabytes = (Bytes / 1024 / 1024) */ free_meg := lsectors_per_cluster * lbytes_per_sector * lnumber_of_free_clusters / 1024 / 1024; Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
DBMS_OUTPUT.PUT_LINE('free disk space, megabytes = ' || free_meg); END; On my machine, this fragment produces the following output: free disk space, megabytes = 214.53515625 Of course, you could put this computation in a named function or procedure, and even make it part of the disk_util package. Figure 21.1: Invoking an external procedure 21.1.2 Architecture Let's take a look at what happens when you invoke an external procedure. As shown in Figure 21.1, the process flow starts with a PL/SQL application that calls a special PL/SQL "module body." In our example above, this body defines the get_disk_free_space function. PL/SQL then looks for a special Net8 listener[3] process, which should already be running in the background. At this point, the listener will spawn an executable program called extproc. This process loads the dynamic library and then invokes the desired routine in the shared library, whereupon it returns its results back to PL/ SQL. [3] Net8 is the name for what was formerly the Oracle SQL*Net product. A Net8 Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
listener is a background process, typically configured by the DBA, which enables other processes to connect to a given service such as the Oracle server. To limit overhead, only one extproc process needs to run for a given Oracle session; this process starts with the first external procedure call and terminates when the session exits. For each distinct external procedure you call, this extproc process loads the associated shared library, but only if it hasn't already been loaded. In case you are unfamiliar with dynamic linking, we've provided a few words of explanation. Calling a dynamically linked routine simply maps the shared code pages into the address space of the "user" process. Then, when that process touches one of the pages of the shared library, it will be paged into physical memory, if it isn't already there. The resident pages of the mapped shared library file will be shared automatically between users of that library.[4] In practical terms, this means that heavy concurrent use of your external procedure often requires a lot less computer processing power and memory than, say, the primitive approach you might take with database pipes. [4] This description applies to Sun's Solaris operating system as well as to Windows NT. For a more detailed discussion from a UNIX perspective, see Adrian Cockroft's performance column, "Which is Better -- Static or Dynamic Linking?" in SunWorld Online, February 1996, at http://www.tritec.de/sunworldonline/swol-02-1996/swol-02- perf.html. 21.1.3 Advantages Oracle has provided a number of features that make external procedures truly an industrial-strength resource. The four major features are summarized here. q Oracle external procedures use shared libraries rather than executables. Requiring the external routine to be in a dynamically linked library, rather than in a statically linked module, helps prevent heavy use of the procedure from consuming your machine. By contrast, static linking means that all of the necessary libraries are actually copied into your compiled program, and each execution requires its own address space. By requiring a library rather than a program, Oracle further allows you to bundle many different external routines conveniently together into a single shared library file. Co-locating a family of related routines in one shared library provides the benefits of increased performance as well as manageability. q Oracle external procedures run in a separate memory space from the main kernel processes. This is a good thing; it makes it easy to prevent your custom code from stepping on the memory used by the database server. While it is technically possible to write an external procedure that would crash the Oracle server, you have to set out to do so. If the external procedure crashes, the companion process, extproc, returns an error to the PL/SQL engine, which in turn reports it to the application. q External procedures provide full transaction support; that is, they can participate fully in the current transaction. By accepting "context" information from PL/SQL, the procedure can call back to the database to fetch data, make SQL or PL/SQL calls, and raise exceptions. In the current release, utilizing these features requires some low-level Oracle Call Interface (OCI) Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
programming...but at least it's possible! q Oracle enforces the execution of external procedures with database-level security. At the first level of security, only the DBA can execute or grant privileges on the required CREATE LIBRARY statement that tells Oracle where the operating system file exists. At the next level of security, users may only invoke the external procedure if they are granted EXECUTE privilege on it. 21.1.4 Limitations External procedures are not perfect, although their benefits far outweigh their shortcomings. I have no doubt that external procedures will find uses in many applications. Here are some of the current limitations of these procedures: q Despite the wonders of shared libraries, Oracle's architecture requires an unavoidable amount of interprocess communication. Moreover, in Oracle 8.0, extproc is single-threaded; while there is only one external procedure process per session, each session does require its own process. (A future version may be multi-threaded, allowing sessions to share a smaller number of extproc processes.) q External procedures (at least, as they are implemented in their first release) cannot pass parameters of any user-defined type. Arguments must be conventional scalars. If you wish to exchange objects or collections, a possible workaround is to write a PL/SQL module that would split them up into scalars before calling the external procedure, and reassemble them upon return. q With Oracle's current implementation, extproc closes the shared library after it's called, meaning that libraries are not cached. Although this approach could save memory, it could also mean more of a CPU hit for subsequent calls. In addition, the overhead for the first external procedure call from a given session may result in a noticeable delay in response time; however, subsequent calls are much faster. Previous: 20.8 Postscript: Oracle PL/SQL Next: 21.2 Steps in Using the BFILE Datatype Programming, 2nd Edition Creating an External Procedure 20.8 Postscript: Using the Book Index 21.2 Steps in Creating an BFILE Datatype External Procedure The Oracle Library Navigation Copyright (c) 2000 O'Reilly & Associates. All rights reserved. Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
Previous: 21.1 Introduction Chapter 21 Next: 21.3 Syntax for to External Procedures External Procedures External Procedures 21.2 Steps in Creating an External Procedure Before you try external procedures, be sure that the machine where you're running the Oracle server supports shared or dynamically linked libraries. Virtually all UNIX machines qualify, as do Windows NT machines. If your own machine doesn't qualify, you can stop here, or you can investigate the use of distributed external procedures. These are your next tasks: 1. Ensure that your DBA has enabled a listener for external procedures in your Net8 environment. (This involves changes to tnsnames.ora and listener.ora.) This is a one-time job for a given server. 2. Identify or create the .so or .DLL file which contains the shared library. 3. In Oracle, issue the SQL statement CREATE LIBRARY..., which defines an alias in the data dictionary for the external shared library file. This registers the program with the database engine so that it knows where to find it when it is called. 4. Create the PL/SQL function or procedure body, typically within a package, that will register with PL/SQL the desired routine from the external library. The body of the procedure or function will use the EXTERNAL clause in place of a BEGIN...END block. And that's it! Let's look at each step in more detail, focusing on the implementation of a random number generator for PL/SQL. 21.2.1 Step 1: Set Up the Listener What actually happens when your code needs to use the external procedure? First, your code calls a predefined PL/SQL body. When the PL/SQL runtime engine notices such a call, it looks for the special Net8 listener named EXTERNAL_PROCEDURE_LISTENER, which in turn spawns a session-specific process called extproc. It is extproc that invokes your routine in the shared library. You need to create a new listener with a specific name, EXTERNAL_PROCEDURE _LISTENER. This listener process will execute alongside other listener(s) that you already have running. NOTE: You cannot change the names EXTERNAL_PROCEDURE_LISTENER or Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
extproc. In the listener.ora fragment given, everything that's not in lowercase italics must match the listing. In your listener.ora file, you will need the following entries: /* filename on companion disk: lsnrfrag.ora /* EXTERNAL_PROCEDURE_LISTENER = (ADDRESS_LIST = (ADDRESS = (PROTOCOL=IPC) (KEY=epsid) ) ) SID_LIST_EXTERNAL_PROCEDURE_LISTENER = (SID_LIST = (SID_DESC= (SID_NAME=epsid) (ORACLE_HOME=full_directory_path) (PROGRAM=extproc) ) ) Where: epsid A short identifier that is used by Net8 to locate the listener. Its actual name is rather arbitrary, since your programs will never see it. epsid has to be the same identifier in the address list and in the SID list. full_directory_path The full pathname to your ORACLE_HOME directory, such as /u01/app/oracle/product/8.0.3 on UNIX or C:\ORANT on Windows NT. Notice that there are no quotes around the directory name. NOTE: If desired, listener.ora can point the listener's log into your desired directory: LOG_DIRECTORY_EXTERNAL_PROCEDURE_LISTENER=/u01/ app/ oracle/admin/SID/logbook And, for debugging, you can control "tracing" for your new listener with entries like this: Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
TRACE_DIRECTORY_EXTERNAL_PROCEDURE_LISTENER=/u01/ app/ oracle/admin/SID/logbook TRACE_LEVEL_EXTERNAL_PROCEDURE_LISTENER=user The tnsnames.ora file on the machine where the server is running will need an entry like the following: EXTPROC_CONNECTION_DATA = (DESCRIPTION = (ADDRESS = (PROTOCOL=IPC) (KEY=epsid) ) (CONNECT_DATA= (SID=epsid)) ) ) Again, epsid must match the key used in the listener.ora file. TIP: If you intend to use external procedures on your server, remember to modify your database startup and shutdown procedures to incorporate the listener start and stop commands. On UNIX, this typically means editing a startup shell script. On Windows NT, a Net8 listener is automatically installed as a system service the first time you start it from the command line. However, the listener will not launch automatically on boot unless you configure it to do so. You can use the control panel to designate which listeners launch on system startup. To remove the external procedure service on NT, delete the entries from listener.ora and tnsnames.ora, and use the NT command instsrv remove as follows: instsrv OracleTNSListener80external_procedure_listener remove (The instsrv utility is available in the NT 4.0 Server Resource Kit. Without it, you'll probably have to edit the registry.) After making these configuration file changes, you'll need to start the new listener process. In UNIX, this is typically performed from the command line: lsnrctl start external_procedure_listener Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
If your database server is running on Windows NT, the first time you start the listener, you'll use the LSNRCTL80 command. From the command prompt, for example, the command would be: LSNRCTL80 start external_procedure_listener Thereafter (on NT) you can start and stop specific listeners from the Services component of the Control Panel. 21.2.2 Step 2: Identify or Create the Shared Library Step 1 is completely independent of any external procedure that you may create on your system. The remaining steps, while specific to our random number procedure, include discussion that applies to almost any external procedure. Although later examples will show how to create your own shared libraries, let's start with an example that requires no C language programming: calling a standard C library function, rand, which generates a 16-bit random number. On many platforms, rand already exists in a shared object library; on UNIX, it's often in /lib/libc.so, and on NT, in c:\winnt\system32\CRTDLL.DLL.[5] [5] Documentation on available library functions is commonly available in UNIX man pages or in SDK documentation on other platforms. A bit of background is in order for folks who haven't played with random number generators. Random number algorithms have certain quirks you need to realize. First, such generators can be deterministic; that is, the algorithm may return the same sequence of "random numbers" every time unless first "seeded" with a quasi-random number. Often, the previous random number is stored and used as a seed. But for the very first call, your program provides the seed, perhaps using some function of the current system time. If you call rand later with an identical seed value, you will get an identical pseudo-random sequence. rand has a companion "seeding" function, srand, that allows you to supply your own seed value. Calling srand before calling rand stores the seed value as a global in memory, for use by the next call to rand. Subsequent calls from the same session need not call srand, since rand will re-seed itself. 21.2.3 Step 3: Issue CREATE LIBRARY Statement Now that we have identified /lib/libc.so as the file containing our needed functions, the next thing we have to do is create a library in the Oracle database. This is the easy part! Creating a library is a way of telling Oracle that we want to refer to a specific shared object file by a programmer-defined name. For many UNIX systems, /lib/libc.so will contain the needed function as shown here: Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
CREATE OR REPLACE LIBRARY libc_l AS '/lib/libc.so'; Executing this command requires the CREATE LIBRARY privilege (see Section 21.3, "Syntax for External Procedures" for more details). Note that we have to use a fully qualified pathname; attempting to use an environment variable such as $ORACLE_BASE in the filename will not work. If your database server runs on Windows NT, your library would likely be created as follows: CREATE OR REPLACE LIBRARY libc_l AS 'c:\winnt\system32\CRTDLL.DLL'; Regardless of platform, you only need to create a single library in this fashion for each shared object file you use. That is, even though you have only issued a single CREATE LIBRARY command for libc.so (or CRTDLL.DLL), you can define any number of external procedures that use routines from that file. 21.2.4 Step 4: Create the PL/SQL Body The final step is to create a function or procedure definition which registers the desired routine from the shared library. This feature lets you write the body of a PL/SQL procedure or function in C instead of PL/SQL. To the caller it looks like any other PL/SQL subprogram. Assuming that your C language skills are ready for any custom programming needed in Step 3, Step 4 is potentially the most complex one. Because of the differences between PL/SQL arguments and C language arguments (in datatype, character set, whether they can be null, etc.), Oracle provides a lot of "instrumentation" to allow you to properly map PL/SQL arguments to C language arguments. The details of this instrumentation are described in Section 21.4, "Mapping Parameters" later in this chapter. TIP: All of the samples in this chapter put the needed modules in a PL/SQL package. One of many benefits of packages is that they enable us to use the RESTRICT_REFERENCES pragma with our module(s). This pragma allows us to tell Oracle that the user-defined function is "safe" and can therefore be used in SQL statements. (See Chapter 17, Calling PL/SQL Functions in SQL, for a full discussion of this pragma.) Returning once again to our random number example, the specification for an appropriate PL/SQL package might look like this: Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
/* Filename on companion disk: rand_utl.sql */ CREATE OR REPLACE PACKAGE random_utl AS FUNCTION rand RETURN PLS_INTEGER; PRAGMA RESTRICT_REFERENCES (rand, WNDS, RNDS, WNPS, RNPS); PROCEDURE srand (seed IN PLS_INTEGER); PRAGMA RESTRICT_REFERENCES (srand, WNDS, RNDS, WNPS, RNPS); END random_utl; Notice that the package specification is completely devoid of clues that we intend to implement the two subprograms as external procedures. We can't yet tell that rand and srand are any different from conventional PL/SQL modules. And that is exactly the point! From a usage perspective, external procedures are interchangeable with conventional procedures. Our package body is blissfully short. By the way, assuming that your library is defined correctly, this package will work as-is on either UNIX or Windows NT. (Even in cases where you can't use the same external code on different operating systems, it may be possible to make the PL/SQL specification the same. You could then make the external code the only thing that differs -- which would be very desirable if you have to support multiple platforms.) CREATE OR REPLACE PACKAGE BODY random_utl AS /* Tested with: (1) Solaris 2.5.1 and Oracle 8.0.3 || (2) Windows NT 4.0 and Oracle 8.0.3 */ FUNCTION rand RETURN PLS_INTEGER /* Return a random number between 1 and (2**16 - 1), using || the current seed value. */ IS EXTERNAL -- tell PL/SQL that this is an external procedure LIBRARY libc_l -- specify the library that we created above NAME "rand" -- function's real name is lowercase LANGUAGE C; -- we are calling a function written in C PROCEDURE srand (seed IN PLS_INTEGER) /* Store a seed value used by external rand() function Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
*/ IS EXTERNAL LIBRARY libc_l NAME "srand" -- srand (lowercase) is function's real name LANGUAGE C PARAMETERS (seed ub4); -- map to unsigned four- byte integer END random_utl; In this example, we have chosen to make the names of the PL/SQL modules identical to those in the shared object library. It is not necessary that they match; in fact, you may wish to make them different so that you can talk about (or document) the parameters independently. Notice the PARAMETERS clause in the body of srand. Each of the formal parameters to the PL/SQL module must have at least one corresponding entry in a PARAMETERS clause. Although there is an extensive set of defaults which can eliminate the need for this clause, this explicit PARAMETERS clause makes it perfectly clear how the parameters will be mapped between PL/SQL and C. 21.2.5 Using the rand External Procedure Now that we've "registered" the external procedure with a PL/SQL package, we can test it: SET SERVEROUTPUT ON SIZE 100000 DECLARE rnd_value PLS_INTEGER; seed PLS_INTEGER; BEGIN /* Generate a seed value from the current system time. */ SELECT TO_CHAR(SYSDATE, 'SSSSS') INTO seed FROM DUAL; /* Call the srand external procedure to store our seed in memory. */ random_utl.srand (seed); /* Now demonstrate some random numbers. */ FOR v_cnt IN 1 .. 10 LOOP rnd_value := random_utl.rand; DBMS_OUTPUT.PUT_LINE ('rand() call #' || v_cnt || ' returns ' || rnd_value); END LOOP; END; Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
This brief test routine simply seeds the library routine with a quasi-random number derived from the current system time, then calls the random number generator ten times in a row. One of our trial runs produced the following results: rand() call #1 returns 27610 rand() call #2 returns 27964 rand() call #3 returns 27908 rand() call #4 returns 21610 rand() call #5 returns 14085 rand() call #6 returns 14281 rand() call #7 returns 9569 rand() call #8 returns 9397 rand() call #9 returns 24266 rand() call #10 returns 142 Limitations of rand It doesn't take a rocket scientist to see that the numbers from our trial run are not totally random. This isn't Oracle's fault! The problem lies with the algorithm used in rand. Moreover, rand returns numbers only in the range 1 through 65535. Many C libraries include the XPG4 standard function rand48, which overcomes these limitations at the expense of mildly increased complexity. See the companion diskette for the source code of an external procedure that uses rand48 (the rand48ut.c and rand48ut.sql files). Previous: 21.1 Introduction Oracle PL/SQL Next: 21.3 Syntax for to External Procedures Programming, 2nd Edition External Procedures 21.1 Introduction to External Book Index 21.3 Syntax for External Procedures Procedures The Oracle Library Navigation Copyright (c) 2000 O'Reilly & Associates. All rights reserved. Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
Previous: 21.2 Steps in Chapter 21 Next: 21.4 Mapping Creating an External External Procedures Parameters Procedure 21.3 Syntax for External Procedures Now that we've gone through the basic steps and seen examples of the kind of code you must write in order to take advantage of external procedures, let's explore each syntactic element in more detail. 21.3.1 CREATE LIBRARY: Creating the External Procedure Library Step 3 in the random number generator example we presented in the previous section uses the SQL statement CREATE LIBRARY. The general syntax for this command is: CREATE [ OR REPLACE ] LIBRARY AS ''; Where: library name A legal PL/SQL identifier. This name will be used in subsequent bodies of external procedures that need to call the shared object (or DLL) file. path to file The fully qualified pathname to the shared object (or DLL) file. As shown above, it must be enclosed in single quotes. Here are some things to keep in mind when issuing a CREATE LIBRARY statement: q The statement must be executed by the DBA or by a user who has been granted CREATE LIBRARY or CREATE ANY LIBRARY privileges. q As with most other database objects, libraries are owned by a specific Oracle user (schema). Other users can refer to the library using owner.library syntax, or they can create synonyms for the library (or use a synonym) if desired. Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
q Oracle doesn't check whether the named shared library file exists when you execute the CREATE LIBRARY statement. Nor will it check when you later create an external procedure declaration for a function in that library (see Step 4). If you have a syntax error in the path, you won't know it until the first time you try to execute the function. q Setting up a listener is typically a DBA task performed (in UNIX, anyway) when the DBA is logged on as the "oracle user." However, for security reasons, Oracle recommends setting up a different OS-level user with a limited profile to run the listener for external procedures. 21.3.2 EXTERNAL: Creating the PL/SQL Body In lieu of a BEGIN..END block, the body of your PL/SQL function or procedure must contain an EXTERNAL clause. This section describes the content of this clause. Syntactically, it looks like this: EXTERNAL LIBRARY [ NAME ] [ LANGUAGE ] [ CALLING STANDARD C | PASCAL ] [ PARAMETERS () ] [ WITH CONTEXT ]; Where: library name Name defined previously in the CREATE LIBRARY statement. external routine name Name of the function as defined in the C language library. If the name is lowercase, you must put double quotes around it. You can omit this parameter; if you do, the name of the external routine must match your PL/SQL module's name (defaults to uppercase). language name Lets PL/SQL know the language in which the external routine is written. In early releases of Oracle8, this parameter can only be C, which is the default. CALLING STANDARD On Windows NT, your application may use the Pascal calling standard, which means that arguments are "reversed" on the stack and that your called function will deal with them accordingly. CALLING STANDARD defaults to C if omitted. PARAMETERS This section gives the position and datatypes of parameters exchanged between PL/SQL and C. external parameter list Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
External parameters appear in a comma-delimited list. Each item in the list is one of three things: r The keyword CONTEXT, which is a placeholder for the context pointer r Information about a formal parameter's mapping between PL/SQL and C r The keyword RETURN and information about its mapping The syntax and rules are discussed in "Mapping Parameters" below. WITH CONTEXT The presence of this clause indicates that you want PL/SQL to pass a "context pointer" to the called program. The called program must be expecting the pointer as a formal parameter of type OCIExtProcContext * (defined in the C header file ociextp.h). This "context" that we are passing via a pointer is a data structure that contains a variety of Oracle-specific information. The called procedure doesn't actually refer directly to the data structure's content; instead, the structure simply facilitates other Oracle Call Interface (OCI) calls which perform various Oracle-specific tasks. These tasks include raising predefined or user-defined exceptions, allocating session-only memory (which gets released as soon as control returns to PL/SQL), and obtaining information about the Oracle user's environment. 21.3.3 DROP: Dropping Libraries The syntax for dropping a library is simply: DROP LIBRARY ; The Oracle user who executes this command must have the DROP LIBRARY or DROP ANY LIBRARY privilege. Oracle does not check dependency information before dropping the library. This is useful if you need to change the name or location of the shared object file to which the library points. You can just drop it and rebuild it, and any dependent routines will continue to function. (More useful, perhaps, would be a requirement that you use a DROP LIBRARY FORCE command, but such an option does not exist). Before you drop the library permanently, you'll probably want to look in the DBA_DEPENDENCIES view to see if any PL/SQL module relies on the library. Previous: 21.2 Steps in Oracle PL/SQL Next: 21.4 Mapping Creating an External Programming, 2nd Edition Parameters Procedure Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.