Oracle Built−in Packages- P93 ppsx

r2 Raw string to XOR with r1 9.2.3.4.1 Restrictions This program asserts the following purity level with the RESTRICT_REFERENCES pragma: PRAGMA RESTRICT_REFERENCES(BIT_XOR, WNDS, RNDS, WNPS, RNPS); 9.2.3.4.2 Example To toggle a bit (if it is off, turn it on, and if it is on, turn it off) in a bit flag variable using a bitmask, use the BIT_XOR function as follows: DECLARE fourteenth VARCHAR2(8); fifteenth VARCHAR2(8); twentieth VARCHAR2(8); mask RAW(4); bitfield1 VARCHAR2(8); bitfield2 VARCHAR2(8); BEGIN /* set the bitfield for the 15th through 18th */ bitfield1 := '0003C000'; /* set the bitfield for the 26st */ bitfield2 := '02000000'; /* set the mask for the 14th */ fourteenth := '00002000'; /* set the mask for the 15th */ fifteenth := '00004000'; /* set the mask for the 20th */ twentieth := '00080000'; /* merge the masks for the 14th, 15th and 20th */ mask := UTL_RAW.BIT_OR (HEXTORAW (fourteenth),HEXTORAW (fifteenth)); mask := UTL_RAW.BIT_OR (mask, HEXTORAW (twentieth)); /* check to see IF the bitfields have the 14th or 20th set */ IF UTL_RAW.BIT_AND (mask, HEXTORAW (bitfield1)) = '00000000' THEN DBMS_OUTPUT.PUT_LINE ('bitfield1 is not set'); ELSE DBMS_OUTPUT.PUT_LINE ('bitfield1 is set'); END IF; IF UTL_RAW.BIT_AND (mask, HEXTORAW (bitfield2)) = '00000000' THEN DBMS_OUTPUT.PUT_LINE ('bitfield2 is not set'); ELSE DBMS_OUTPUT.PUT_LINE ('bitfield2 is set'); END IF; /* toggle bit 15 in the mask */ mask := UTL_RAW.BIT_XOR (mask, HEXTORAW (fifteenth)); /* check to see IF the bitfield1 has the 14th, 15th, or 20th set */ IF UTL_RAW.BIT_AND (mask, HEXTORAW (bitfield1)) = '00000000' THEN DBMS_OUTPUT.PUT_LINE ('bitfield1 is not set'); ELSE DBMS_OUTPUT.PUT_LINE ('bitfield1 is set'); END IF; END; / This is the output from the previous example: bitfield1 is set bitfield2 is not set bitfield1 is not set [Appendix A] What's on the Companion Disk? 9.2.3 The UTL_RAW Interface 451 9.2.3.5 The UTL_RAW.CAST_TO_RAW function The CAST_TO_RAW function converts the VARCHAR2 input string into a raw datatype. The data is not altered; only the data type is changed. This is essentially a VARCHAR2_to_RAW function, FUNCTION UTL_RAW.CAST_TO_RAW (c IN VARCHAR2) RETURN RAW; where c is the text string that should be converted to a raw datatype. 9.2.3.5.1 Restrictions This program asserts the following purity level with the RESTRICT_REFERENCES pragma: PRAGMA RESTRICT_REFERENCES(CAST_TO_RAW, WNDS, RNDS, WNPS, RNPS); 9.2.3.5.2 Example For an example of CAST_TO_RAW, see "Section 9.2.3.15, "The UTL_RAW.TRANSLATE function"" later in this chapter. 9.2.3.6 The UTL_RAW.CAST_TO_VARCHAR2 function The CAST_TO_VARCHAR2 function converts the raw input string into a VARCHAR2 datatype. The data is not altered; only the data type is changed. The current NLS language is used. The specification is, FUNCTION UTL_RAW.CAST_TO_VARCHAR2 (r IN RAW) RETURN VARCHAR2; where r is the raw string that should be converted into a VARCHAR2. 9.2.3.6.1 Restrictions This program asserts the following purity level with the RESTRICT_REFERENCES pragma: PRAGMA RESTRICT_REFERENCES(CAST_TO_VARCHAR2, WNDS, RNDS, WNPS, RNPS); 9.2.3.6.2 Example The data dictionary views USER_TAB_COLUMNS, ALL_TAB_COLUMNS, and DBA_TAB_COLUMNS have the first 32 bytes of the lowest and highest data values for each column in analyzed tables. Unfortunately, this data is of data type RAW and not very readable by humans. The CAST_TO_VARCHAR2 function can be used on character datatype columns to see these data in more readable form. SELECT column_name, UTL_RAW.CAST_TO_VARCHAR2(low_value) ,UTL_RAW.CAST_TO_VARCHAR2(high_value) FROM user_tab_columns WHERE table_name = 'FOO_TAB' AND column_name = 'VCHAR1' 9.2.3.7 The UTL_RAW.COMPARE function The COMPARE function does a binary compare of the two raw input strings and returns the number of the first byte position where the two strings differ. If the two strings are identical, a zero is returned. If the two input strings are different lengths, then the pad character is repeatedly appended to the shorter string, extending it to the length of the longer string. The default pad character is 0x00 (binary zero). [Appendix A] What's on the Companion Disk? 9.2.3 The UTL_RAW Interface 452 FUNCTION UTL_RAW.COMPARE (r1 IN RAW ,r2 IN RAW ,pad IN RAW DEFAULT NULL) RETURN NUMBER; The parameters for this program are summarized in this table. Parameter Description r1 The first input string to compare r2 The second input string to compare pad The single character used to right pad the shorter of two unequal length strings 9.2.3.7.1 Restrictions This program asserts the following purity level with the RESTRICT_REFERENCES pragma: PRAGMA RESTRICT_REFERENCES(COMPARE, WNDS, RNDS, WNPS, RNPS); 9.2.3.7.2 Example Here is an example of the COMPARE function: DECLARE r_string1 RAW(16); r_string2 RAW(16); diff_position INTEGER; BEGIN r_string1 := UTL_RAW.CAST_TO_RAW('test string1'); r_string2 := UTL_RAW.CAST_TO_RAW('test string2'); diff_position := UTL_RAW.COMPARE(r_string1,r_string2); DBMS_OUTPUT.PUT_LINE ( 'r_string1='|| UTL_RAW.CAST_TO_VARCHAR2(r_string1)); DBMS_OUTPUT.PUT_LINE ( 'r_string2='|| UTL_RAW.CAST_TO_VARCHAR2(r_string2)); DBMS_OUTPUT.PUT_LINE ('diff_position='|| diff_position); END; / Sample output follows: r_string1=test string1 r_string2=test string2 diff_position=12 9.2.3.8 The UTL_RAW.CONCAT function The CONCAT function is used to concatenate a set of 12 raw strings into a single raw string. The size of the concatenated result must not exceed 32K or the procedure will raise the ORA−6502 exception. FUNCTION UTL_RAW.CONCAT (r1 IN RAW DEFAULT NULL ,r2 IN RAW DEFAULT NULL ,r3 IN RAW DEFAULT NULL ,r4 IN RAW DEFAULT NULL ,r5 IN RAW DEFAULT NULL ,r6 IN RAW DEFAULT NULL ,r7 IN RAW DEFAULT NULL ,r8 IN RAW DEFAULT NULL ,r9 IN RAW DEFAULT NULL [Appendix A] What's on the Companion Disk? 9.2.3 The UTL_RAW Interface 453 ,r10 IN RAW DEFAULT NULL ,r11 IN RAW DEFAULT NULL ,r12 IN RAW DEFAULT NULL) RETURN RAW; The parameters for this program are summarized in this table. Parameter Description r1 First piece of raw data to be concatenated r2 Second piece of raw data to be concatenated r3 Third piece of raw data to be concatenated r4 Fourth piece of raw data to be concatenated r5 Fifth piece of raw data to be concatenated r6 Sixth piece of raw data to be concatenated r7 Seventh piece of raw data to be concatenated r8 Eighth piece of raw data to be concatenated r9 Ninth piece of raw data to be concatenated r10 Tenth piece of raw data to be concatenated r11 Eleventh piece of raw data to be concatenated r12 Twelfth piece of raw data to be concatenated 9.2.3.8.1 Exceptions The VALUE_ERROR exception (ORA−6502) is raised if the returned raw string exceeds 32K. The documentation from 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.8.2 Restrictions This program asserts the following purity level with the RESTRICT_REFERENCES pragma: PRAGMA RESTRICT_REFERENCES(CONCAT, WNDS, RNDS, WNPS, RNPS); 9.2.3.8.3 Example For an example of CONCAT, see the example for TRANSLATE. 9.2.3.9 The UTL_RAW.CONVERT function The CONVERT function converts the input raw string r from one installed NLS character set to another installed NLS character set. Here's the specification: FUNCTION UTL_RAW.CONVERT (r IN RAW ,to_charset IN VARCHAR2 ,from_charset IN VARCHAR2) RETURN RAW; Parameters are summarized in the following table. Parameter Description [Appendix A] What's on the Companion Disk? 9.2.3 The UTL_RAW Interface 454 r The raw string to be converted to_charset The name of the output NLS character set from_charset The name of the input NLS character set 9.2.3.9.1 Exceptions The VALUE_ERROR exception (ORA−6502) is raised if the input raw string is missing, NULL, or has zero length. This exception is also raised if the from_charset or to_charset parameters are missing, NULL, zero length, or name an invalid character set. 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.9.2 Restrictions This program asserts the following purity level with the RESTRICT_REFERENCES pragma: PRAGMA RESTRICT_REFERENCES(CONVERT, WNDS, RNDS, WNPS, RNPS); 9.2.3.10 The UTL_RAW.COPIES function The COPIES function concatenates the input raw string r, n number of times. Here's the specification: FUNCTION UTL_RAW.COPIES (r IN RAW ,n IN NUMBER) RETURN RAW; The parameters for this program are summarized in this table. Parameter Description r The input raw string that is to be copied n The number of copies of the input string to make (must be positive) 9.2.3.10.1 Exceptions The VALUE_ERROR exception (ORA−6502) is raised if the input raw string r is missing, NULL, or has zero length. This exception is also raised if the input number of copies n is less than 1 (n < 1). 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.10.2 Restrictions This program asserts the following purity level with the RESTRICT_REFERENCES pragma: PRAGMA RESTRICT_REFERENCES(COPIES, WNDS, RNDS, WNPS, RNPS); 9.2.3.10.3 Example Here is an example of the COPIES function: DECLARE r_string1 RAW(64); r_repeat RAW(16); BEGIN r_repeat := UTL_RAW.CAST_TO_RAW('Test '); r_string1 := UTL_RAW.COPIES(r_repeat,4); DBMS_OUTPUT.PUT_LINE ( [Appendix A] What's on the Companion Disk? 9.2.3 The UTL_RAW Interface 455 . VALUE_ERROR exception (ORA−6502) is raised if the returned raw string exceeds 32K. The documentation from Oracle 7.3 and 8.0 indicates that this is to be revised in a future release, so don't count. parameters are missing, NULL, zero length, or name an invalid character set. 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. also raised if the input number of copies n is less than 1 (n < 1). 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