Oracle Built−in Packages- P95 pptx

r_lower := UTL_RAW.XRANGEUTL_RAW.CAST_TO_RAW'a', UTL_RAW.CAST_TO_RAW'z'; /* Create a raw string of uppercase followed by lowercase letters */ r_upper_lower := UTL_RAW.CONCATr_upper , r

r_lower := UTL_RAW.XRANGE(UTL_RAW.CAST_TO_RAW('a'),

UTL_RAW.CAST_TO_RAW('z'));

/* Create a raw string of uppercase followed by lowercase letters */

r_upper_lower := UTL_RAW.CONCAT(r_upper , r_lower);

/* Create a raw string of lowercase followed by uppercase letters */

r_lower_upper := UTL_RAW.CONCAT(r_lower , r_upper);

/* Translate upper to lower and lower to upper for the input string */

r_out := UTL_RAW.TRANSLATE(r_in , r_upper_lower , r_lower_upper );

/* Convert the result back to varchar2 and return the result */

return(UTL_RAW.CAST_TO_VARCHAR2(r_out));

END;

/

Sample output follows:

SQL> select switch_case('This Is A Test') from dual;

SWITCH_CASE('THISISATEST')

−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−

tHIS iS a tEST

9.2.3.16 The UTL_RAW.TRANSLITERATE function

The TRANSLITERATE function translates bytes in the input raw sting r, substituting bytes found in from_set with positionally corresponding bytes in to_set The translated string is returned Bytes in r that do not appear

in from_set are not modified If from_set is longer than to_set, then the unmatched bytes in from_set are right−padded with the pad byte The return string is always the same length as the input string r The

specification follows:

FUNCTION UTL_RAW.TRANSLITERATE

(r IN RAW

,to_set IN RAW DEFAULT NULL

,from_set IN RAW DEFAULT NULL

,pad IN RAW DEFAULT NULL)

RETURN RAW;

TRANSLITERATE is similar to TRANSLATE, but it differs in that the return string is always the same length as the input string (r) TRANSLITERATE is just like TRANSLATE if to_set and from_set are the same length If from_set is longer than to_set, then to_set is right−padded with the pad byte

TRANSLITERATE allows NULL from_set, to_set, and pad parameters

Parameters are summarized in the following table

Parameter Description

r Input string to be translated

from_set The list of bytes to be translated; the default is 0x00 through 0xFF

to_set The list of bytes that from_set bytes are translated to; the default is NULL

pad If from_set is shorter than to_set, then this pad byte is the translation character for any unmatched

bytes in from_set; the default is 0x00

9.2.3.16.1 Exceptions

The VALUE_ERROR exception (ORA−6502) is raised if r is null or has 0 length The documentation from

both Oracle 7.3 and 8.0 indicates that this is to be revised in a future release, so don't count on this exception

to remain unchanged

9.2.3.16.2 Restrictions

This program asserts the following purity level with the RESTRICT_REFERENCES pragma:

PRAGMA RESTRICT_REFERENCES(TRANSLITERATE, WNDS, RNDS, WNPS, RNPS);

9.2.3.16.3 Example

An example use of TRANSLITERATE is a make_lower function that switches uppercase characters in a text string to lowercase characters, converting spaces, dashes, and dots to underscores This function also makes use of other UTL_RAW functions: CAST_TO_RAW, XRANGE, and CONCAT This method may not be the most efficient technique for this conversion, but it serves to demonstrate some UTL_RAW functions in an easily understandable context

CREATE OR REPLACE FUNCTION make_lower(c_in IN VARCHAR2)

RETURN VARCHAR2

IS

r_in RAW(2000);

r_out RAW(2000);

r_upper RAW(48);

r_lower RAW(32);

r_underscore RAW(1);

BEGIN

−− convert the input to raw

r_in := UTL_RAW.CAST_TO_RAW(c_in);

r_underscore := UTL_RAW.CAST_TO_RAW('_');

−− start the from characters with the uppercase letters

r_upper :=

UTL_RAW.XRANGE(UTL_RAW.CAST_TO_RAW('A'),UTL_RAW.CAST_TO_RAW('Z'));

−− space, dash and dot to the from list of characters

r_upper := UTL_RAW.CONCAT(r_upper,UTL_RAW.CAST_TO_RAW(' ')

,UTL_RAW.CAST_TO_RAW('−'),UTL_RAW.CAST_TO_RAW('.'));

−− set the to characters to be lowercase letters

r_lower :=

UTL_RAW.XRANGE(UTL_RAW.CAST_TO_RAW('a'),UTL_RAW.CAST_TO_RAW('z'));

−− convert the uppercase to lowercase and punctuation marks to underscores

r_out := UTL_RAW.TRANSLITERATE(r_in , r_lower , r_upper, r_underscore);

−− return the character version

return(UTL_RAW.CAST_TO_VARCHAR2(r_out));

END;

Sample output follows:

SQL> exec DBMS_OUTPUT.PUT_LINE (make_lower('This.is−A tEst'));

this_is_a_test

9.2.3.17 The UTL_RAW.XRANGE function

The XRANGE function returns a raw string containing all bytes in order beginning with the start_byte

parameter and ending with end_byte If start_byte is greater than end_byte, then the return string wraps from 0XFF to 0X00

FUNCTION UTL_RAW.XRANGE

(start_byte IN RAW DEFAULT 0x00

,end_byte IN RAW DEFAULT 0xFF)

RETURN RAW;

The parameters for this program are summarized in the following table

Parameter Description

start_byte Start byte; the default is 0x00.

end_byte End byte; the default is 0xFF

9.2.3.17.1 Restrictions

This program asserts the following purity level with the RESTRICT_REFERENCES pragma:

PRAGMA RESTRICT_REFERENCES(XRANGE, WNDS, RNDS, WNPS, RNPS);

9.2.3.17.2 Example

For an example of XRANGE, see the example for TRANSLATE or TRANSLITERATE

9.2.4 UTL_REF: Referencing Objects (Oracle8.0.4)

The UTL_REF package provides a PL/SQL interface that allows you to select and modify objects (instances

of an object type) in an object table without having to specify or know about the underlying database table

With UTL_REF, you only need a reference to the object in order to identify it in the database and perform the

desired operations With UTL_REF, you can do any of the following:

•

Select or retrieve an object from the database

•

Lock an object so that no other session can make changes to the object

•

Select and lock an object in a single operation (similar to SELECT FOR UPDATE)

•

Update the contents of an object

•

Delete an object

You will typically use UTL_REF programs when you have references to an object and one of the following is true:

•

You do not want to have to resort to an SQL statement to perform the needed action

•

You do not even know the name of the table that contains the object, and therefore cannot rely on

SQL to get your job done

Before getting into the details, let's start with an initial example of how you might use the UTL_REF

packages

You will be able to use UTL_REF programs only to select or modify objects in an object table An object table is a table in which each row of the table is an object Here are the steps one might take to create an object table

First, create an object type:

CREATE TYPE hazardous_site_t IS OBJECT (

name VARCHAR2(100),

location VARCHAR2(100),

dixoin_level NUMBER,

pcb_level NUMBER,

METHOD FUNCTION cleanup_time RETURN NUMBER);

Now you can create a table of these objects:

CREATE TABLE hazardous_sites OF hazardous_site_t;

As you will see in the headers for the UTL_REF programs, Oracle has provided a special parameter−passing syntax called ANY This syntax allows us to pass references and objects of any object type in and out of the programs This behavior is not otherwise available in Oracle8 built−in packages or the code that you yourself can write using object types

9.2.4.1 Getting Started with UTL_REF

The UTL_REF package is created when the Oracle8.0.4 (or later) database is installed The utlref.sql script

(found in the built−in packages source code directory, as described in Chapter 1) contains the source code for

this package's specification The script is called by catproc.sql, which is normally run immediately after the

database is created The script creates the public synonym UTL_REF for the package and grants EXECUTE privilege on the package to public All Oracle users can reference and make use of the package

Every program in this package runs as "owner." This means that programs in the UTL_REF package operate within the privileges of the session running those programs You will be able to select and modify only

objects to which your session has been granted the necessary privileges

9.2.4.1.1 UTL_REF programs

Table 9.5 lists the programs defined for the UTL_REF packages

Table 9.5: UTL_REF Programs

SQL DELETE_OBJECT Deletes an object from the underlying object table No LOCK_OBJECT Locks an object so that another session cannot change the object No SELECT_OBJECT Selects an object based on its reference, returning that object as an OUT

argument

No

UPDATE_OBJECT Updates the object specified by the reference by replacing it with the object

you pass to the program

No

UTL_REF does not declare any nonprogram elements

9.2.4.1.2 UTL_REF exceptions

UTL_REF does not declare any exceptions However, you may encounter any of the following Oracle

exceptions when running the UTL_REF programs:

ORA−00942

Insufficient privileges You must have the appropriate privileges on the underlying database table

ORA−01031

9.2.4 UTL_REF: Referencing Objects (Oracle8.0.4) 464

Insufficient privileges You attempted to update an object table on which you have only SELECT privileges You must have the appropriate privileges on the underlying database table

ORA−08177

Cannot serialize access for this transaction You have tried to change data after the start of a serialized transaction

ORA−00060

Deadlock detected while waiting for resource Your session and another session are waiting for a resource locked by the other You will need to wait or ROLLBACK

ORA−01403

No data found The REF is NULL or otherwise not associated with an object in the database

9.2.5 UTL_REF Interface

This section describes the programs available through the UTL_REF package A single, extended example at the end of the chapter shows how you might be able to take advantage of the UTL_REF programs in your own applications

9.2.5.1 The UTL_REF.DELETE_OBJECT procedure

Use the DELETE_OBJECT procedure to delete an object (actually, the row containing that object) specified

by the given reference The header is,

PROCEDURE UTL_REF.DELETE_(reference IN REF ANY);

where reference identifies the object

This program effectively substitutes for the following kind of SQL statement:

DELETE FROM the_underlying_object_table t

WHERE REF (t) = reference;

In contrast to this SQL statement, with DELETE_OBJECT you will not need to specify the name of the underlying database object table to retrieve the object

9.2.5.1.1 Restrictions

Note the following restrictions on calling DELETE_OBJECT:

•

The program does not assert a purity level with the RESTRICT_REFERENCES pragma

•

You cannot call this program from within an SQL statement, either directly or indirectly

9.2.5.2 The UTL_REF.LOCK_OBJECT procedure

Use the LOCK_OBJECT procedure to lock or lock and retrieve an object for a given reference The header is overloaded as follows:

PROCEDURE UTL_REF.LOCK_OBJECT (reference IN REF ANY);

PROCEDURE UTL_REF.LOCK_OBJECT

(reference IN REF ANY