'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 [Appendix A] What's on the Companion Disk? 9.2.3 The UTL_RAW Interface 456 ,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); [Appendix A] What's on the Companion Disk? 9.2.3 The UTL_RAW Interface 457 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 [Appendix A] What's on the Companion Disk? 9.2.3 The UTL_RAW Interface 458 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 [Appendix A] What's on the Companion Disk? 9.2.3 The UTL_RAW Interface 459 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' */ [Appendix A] What's on the Companion Disk? 9.2.3 The UTL_RAW Interface 460 . (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. 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. 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