Oracle Built−in Packages- P94 ppsx

'r_string1='||UTL_RAW.CAST_TO_VARCHAR2r_string1;END; / Sample output follows: r_string1=Test Test Test Test 9.2.3.11 The UTL_RAW.LENGTH function The LENGTH function returns the number of

'r_string1='||UTL_RAW.CAST_TO_VARCHAR2(r_string1));

END;

/

Sample output follows:

r_string1=Test Test Test Test

9.2.3.11 The UTL_RAW.LENGTH function

The LENGTH function returns the number of bytes in the raw input string given by the r parameter,

FUNCTION UTL_RAW.LENGTH

(r IN RAW)

RETURN NUMBER;

where r is the raw input string

9.2.3.11.1 Restrictions

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

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

9.2.3.11.2 Example

Here is an example of the LENGTH function:

r_1 RAW(32000);

r_2 RAW(32000);

r_3 RAW(32000);

BEGIN

r_1 := UTL_RAW.XRANGE (hextoraw('00'),hextoraw('FF'));

r_2 := UTL_RAW.CONCAT (r_1,r_1,r_1,r_1,r_1,r_1,r_1,r_1);

r_3 := UTL_RAW.CONCAT (r_2,r_2,r_2,r_2,r_2,r_2,r_2,r_2);

DB<S_OUTPUT.PUT_LINE ('Length of r_1='||UTL_RAW.LENGTH(r_1));

DBMS_OUTPUT.PUT_LINE ('Length of r_2='||UTL_RAW.LENGTH(r_2));

DBMS_OUTPUT.PUT_LINE ('Length of r_3='||UTL_RAW.LENGTH(r_3));

END;

/

Sample output follows:

Length of r_1=256

Length of r_2=2048

Length of r_3=16384

9.2.3.12 The UTL_RAW.OVERLAY function

The OVERLAY function overwrites the specified section of the target raw string with the string specified in the overlay_str parameter and returns the overwritten raw string The overwriting starts pos bytes into the target string and continues for len bytes, right−padding the target with the pad parameter as needed to extend the target, if necessary The len parameter must be greater than 0 and pos must be greater than 1 If pos is greater than the length of the target string, then the target is right−padded with pad before the overlaying begins Here's the specification:

FUNCTION UTL_RAW.OVERLAY

(overlay_str IN RAW

,target IN RAW

,pos IN BINARY_INTEGER DEFAULT 1

,len IN BINARY_INTEGER DEFAULT NULL

pad IN RAW DEFAULT NULL)

RETURN RAW;

The parameters for this program are summarized in the following table

Parameter Description

overlay_str The raw string used to overwrite to target

target The raw string that is to be overlaid/overwritten

pos The byte position in the target to begin overlaying; the default is 1

len The number of bytes to overwrite; the default is the length of overlay_str

pad The pad character to fill in extra space if needed; the default is 0x00

9.2.3.12.1 Exceptions

The VALUE_ERROR exception (ORA−6502) is raised if one of the folowing occurs:

•

The input raw string overlay is NULL or has zero length

•

The input target is missing or undefined

•

The length of the target exceeds the maximum length of a raw, len < 0, or pos < 1

The documentation from both version 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.12.2 Restrictions

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

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

9.2.3.12.3 Example

Here is an example of the OVERLAY function:

DECLARE

r_input RAW(40);

r_overlay RAW(40);

start_position INTEGER;

overlay_length INTEGER;

r_pad RAW(2);

r_output RAW(40);

BEGIN

−− set the parameters

r_input := UTL_RAW.CAST_TO_RAW (

'This is the full length text string');

r_overlay := UTL_RAW.CAST_TO_RAW ('overlaid part');

start_position := 13;

overlay_length := 8;

r_pad := UTL_RAW.CAST_TO_RAW ('.');

r_output := UTL_RAW.OVERLAY (

r_overlay, r_input, start_position, overlay_length,r_pad);

DBMS_OUTPUT.PUT_LINE (

'r_input ='|| utl_raw.cast_to_varchar2(r_input));

DBMS_OUTPUT.PUT_LINE (

'r_output(len 8)='|| UTL_RAW.CAST_TO_VARCHAR2(r_output));

overlay_length := 16;

r_output := UTL_RAW.OVERLAY (

r_overlay, r_input, start_position , overlay_length, r_pad);

DBMS_OUTPUT.PUT_LINE (

'r_output(len16)='|| UTL_RAW.CAST_TO_VARCHAR2(r_output));

END;

/

Sample output follows:

r_input =This is the full length text string

r_output(len 8)=This is the overlaidgth text string

r_output(len16)=This is the overlaid part string

9.2.3.13 The UTL_RAW.REVERSE function

The REVERSE function reverses the input raw string and returns this reversed string

FUNCTION UTL_RAW.REVERSE

(r IN RAW)

RETURN RAW;

9.2.3.13.1 Exceptions

The VALUE_ERROR exception (ORA−6502) is raised if the input raw string (r) is null or has zero 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.13.2 Restrictions

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

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

9.2.3.13.3 Example

Here is an example of the REVERSE function:

DECLARE

r_string RAW(16);

r_reverse RAW(16);

BEGIN

r_string := UTL_RAW.CAST_TO_RAW('Java Beans');

r_reverse := UTL_RAW.REVERSE(r_string);

DBMS_OUTPUT.PUT_LINE (

'r_string='|| UTL_RAW.CAST_TO_VARCHAR2(r_string));

DBMS_OUTPUT.PUT_LINE (

'r_reverse='|| UTL_RAW.CAST_TO_VARCHAR2(r_reverse));

END;

Sample output follows:

r_string=Java Beans

r_reverse=snaeB avaJ

9.2.3.14 The UTL_RAW.SUBSTR function

The SUBSTR function returns a substring of the input raw string r beginning at pos and extending for len bytes If pos is positive, the substring extends len bytes from the left; if pos is negative, the substring extends len bytes from the right (the end backwards) The value of pos cannot be 0 The default for len is to the end of the string r If r is NULL, then NULL is returned Here's the specification:

FUNCTION UTL_RAW.SUBSTR

(r IN RAW

,pos IN BINARY_INTEGER

,len IN BINARY_INTEGER DEFAULT NULL)

RETURN RAW;

Parameters are summarized in the following table

Parameter Description

r The input raw string, from which the substring is extracted

pos The starting position for the substring extraction

len The length of the substring to extract; the default is to the end of the input string r

9.2.3.14.1 Exceptions

The VALUE_ERROR exception (ORA−6502) is raised if pos is 0 or len is less than 0 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.14.2 Restrictions

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

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

9.2.3.14.3 Example

Here is an example of the SUBSTR function:

DECLARE

r_string RAW(32);

r_substring RAW(16);

BEGIN

r_string := UTL_RAW.CAST_TO_RAW('This is the test string');

r_substring := UTL_RAW.SUBSTR(r_string,9,8);

DBS_OUTPUT.PUT_LINE (

'r_string='|| UTL_RAW.CAST_TO_VARCHAR2(r_string));

DBMS_OUTPUT,PUT_LINE (

'r_substring='|| UTL_RAW.CAST_TO_VARCHAR2(r_substring));

END;

Sample output follows:

r_string=This is the test string

r_substring=the test

9.2.3.15 The UTL_RAW.TRANSLATE function

The TRANSLATE 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

removed from the return string Here's the specification:

FUNCTION UTL_RAW.TRANSLATE

(r IN RAW

,from_set IN RAW

,to_set IN RAW)

RETURN RAW;

Parameters are summarized in the following table

Parameter Description

r The input raw string to be translated

from_set The list of bytes to translate

to_set The list of bytes that from_set bytes are translated to

TRANSLATE is similar to TRANSLITERATE; however, with TRANSLATE, the return string can be shorter than the input string r TRANSLITERATE return strings are always the same length as the input string r Also, TRANSLATE requires values for from_set, and to_set while TRANSLITERATE has defaults for these inputs

9.2.3.15.1 Exceptions

The VALUE_ERROR exception (ORA−6502) is raised if the r, from_set, or to_set parameters are NULL or

have zero 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.15.2 Restrictions

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

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

9.2.3.15.3 Example

An example use of TRANSLATE is a switch case function that switches the case of every character in a text string, swapping upper and lowercase characters This function also makes use of other UTL_RAW functions: CAST_TO_RAW, XRANGE, and CONCAT This method may not be the most efficient case−switching technique, but it serves to demonstrate the functions nicely

CREATE OR REPLACE FUNCTION switch_case(c_in IN VARCHAR2)

RETURN VARCHAR2

IS

r_in RAW(2000);

r_out RAW(2000);

r_upper RAW(32);

r_lower RAW(32);

r_upper_lower RAW(64);

r_lower_upper RAW(64);

BEGIN

/* Convert input to raw */

r_in := UTL_RAW.CAST_TO_RAW(c_in);

/* Get raw string of uppercase letters from 'A' to 'Z' */

r_upper := UTL_RAW.XRANGE(UTL_RAW.CAST_TO_RAW('A'),

UTL_RAW.CAST_TO_RAW('Z'));

/* Get raw string of lowercase letters from 'a' to 'z' */