Oracle Built−in Packages- P92 doc

9.2.2 Raw Data Manipulation Concepts This section provides an overview of the types of data manipulation you might perform on raw data. 9.2.2.1 Conversion and coercion Conversion refers to functions that convert raw byte strings to other values. Coercion is a specialized conversion that changes the datatype but not the data itself. UTL_RAW has functions that convert from one NLS language set to another, from one set of raw byte strings to another, and from raw datatypes to VARCHAR2 datatypes (as well as from VARCHAR2 to raw). The coercion operations supported by Oracle involving raw datatypes via the standard SQL functions are raw−to−hex and hex−to−raw; via UTL_RAW functions, they are raw−to−VARCHAR2 and VARCHAR2−to−raw. Notably unsupported are raw−to/from−numeric datatypes and raw−to/from−date datatypes. 9.2.2.2 Slicing and dicing Slicing and dicing refers to functions that divide and combine raw byte strings in various ways. These functions include COMPARE, CONCATENATE, COPY, LENGTH, OVERLAY, REVERSE, and SUBSTRING. 9.2.2.3 Bit−fiddling Bit−fiddling refers to the manipulation of individual bits. Because bits are the smallest possible unit of storage, bit−fiddling provides a highly efficient storage mechanism. Bitmap indexes take advantage of this and offer substantial disk savings over traditional Btree indexes. The Oracle kernel supports the bitwise AND function natively via the undocumented function BITAND(x,x),[1] but the other bitwise operations needed to support bitmasks are supported only via the UTL_RAW package. [1] See the definitions of some V$ tables, such as V$session_wait, in the V$fixed_view_definition view. Bitmasks are commonly used to combine a number of flags or semaphores into a single object as follows: • To see if a bit/flag/semaphore is set, use the bitwise AND function. • To turn a bit on or combine bitmasks, use the bitwise OR function. • To turn a bit off, use the bitwise OR and NOT functions together. • To toggle a bit, use the bitwise XOR function. Other bitwise functions, such as shift left and shift right, are supported in C and other languages, but not in PL/SQL or UTL_RAW. To better understand bitmasks and what these functions do, let's look at some examples of their use. A mask is a bit that represents some data; for example, each day of the month can be represented by one bit as follows. The first of the month is the bit mask: 0000 0000 0000 0000 0000 0000 0000 0001 or hex 0000 0001 [Appendix A] What's on the Companion Disk? 9.2.2 Raw Data Manipulation Concepts 446 The second of the month is the bit mask: 0000 0000 0000 0000 0000 0000 0000 0010 or hex 0000 0002 The 26th of the month is the bit mask: 0000 0010 0000 0000 0000 0000 0000 0000 or hex 0200 0000 And so on. In a single 32−bit string (4 bytes), any combination of days of the month can be set. In a scheduling application, we may want to find out if the variable DayInQuestion has the bit set for the 26th. We can perform a bitwise AND on the variable and the mask like this: DayInQuestion 0000 0111 1111 1000 0000 0000 0000 0000 Bits 20−27 set AND Mask for the 26th 0000 0010 0000 0000 0000 0000 0000 0000 −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−− Result 0000 0010 0000 0000 0000 0000 0000 0000 True Likewise, if the variable needs to be checked for any of the bits 14th through 21st, then the masks for the 14th through 21st can be combined (via bitwise OR) and compared to the variable. DayInQuestion 0000 0111 1111 1000 0000 0000 0000 0000 Bits 20−27 set AND Mask 0000 0000 0001 1111 1110 0000 0000 0000 Bits 14−21 set −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−− Result 0000 0000 0001 1000 0000 0000 0000 0000 True The UTL_RAW package can also be used separately from replication, and offers facilities for manipulating raw data types that are not found elsewhere in the Oracle Server product. Oracle has a robust set of functions available for the structured datatypes RAW, CHARACTER, NUMERIC, and DATE. 9.2.3 The UTL_RAW Interface This section describes the programs available through the UTL_RAW package. 9.2.3.1 The UTL_RAW.BIT_AND function The BIT_AND function performs a bitwise logical AND of two input raw strings. If input strings are different lengths, the return value is the same length as the longer input string. The return value is the bitwise AND of the two inputs up to the length of the shorter input string, with the remaining length filled from the unprocessed data in the longer input string. If either input string is NULL, the return value is NULL. Here's the specification for this function: FUNCTION UTL_RAW.BIT_AND (r1 IN RAW ,r2 IN RAW) RETURN RAW; Parameters are summarized in the following table. Parameter Description r1 Raw string to AND with r2 r2 Raw string to AND with r1 [Appendix A] What's on the Companion Disk? 9.2.3 The UTL_RAW Interface 447 9.2.3.1.1 Restrictions This program asserts the following purity level with the RESTRICT_REFERENCES pragma: PRAGMA RESTRICT_REFERENCES(BIT_AND, WNDS, RNDS, WNPS, RNPS); 9.2.3.1.2 Example To check if a bit is turned on in a bit flag variable using a bitmask, you can use the BIT_AND function. This section of example code also uses the BIT_OR function to merge bitmasks: DECLARE fourteenth VARCHAR2(8); fifteenth VARCHAR2(8); twentieth VARCHAR2(8); mask RAW(4); bitfield1 VARCHAR2(8); bitfield2 VARCHAR2(8); BEGIN /* set bitfield1 for the 15th through 18th */ bitfield1 := '0003C000'; /* set bitfield2 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, 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; 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; END; This is the output from this code: Bitfield1 is set Bitfield2 is Anot set 9.2.3.2 The UTL_RAW.BIT_COMPLEMENT function The BIT_COMPLEMENT function performs a logical NOT, or one's complement, of the raw input string r1. The complement of a raw string flips all 0 bits to 1 and all 1 bits to 0, [Appendix A] What's on the Companion Disk? 9.2.3 The UTL_RAW Interface 448 FUNCTION UTL_RAW.COMPLEMENT (r1 IN RAW) RETURN RAW; where r1 is the raw input string. 9.2.3.2.1 Restrictions This program asserts the following purity level with the RESTRICT_REFERENCES pragma: PRAGMA RESTRICT_REFERENCES(BIT_COMPLEMENT, WNDS, RNDS, WNPS, RNPS); 9.2.3.2.2 Example To turn off a bit, regardless of its original state, in a bit flag variable using a bitmap, you can use the BIT_COMPLEMENT function together with the BIT_AND function. 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)); mask := UTL_RAW.BIT_OR(mask,hextoraw(twentieth)); /* check to see if the bitfields have 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; 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; /* turn off bit 15 in the mask */ mask := UTL_RAW.BIT_AND(mask,UTL_RAW.BIT_COMPLEMENT(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'); [Appendix A] What's on the Companion Disk? 9.2.3 The UTL_RAW Interface 449 else dbms_output.put_line('bitfield1 is set'); end if; END; This is the output from the above code: bitfield1 is set bitfield2 is not set bitfield1 is not set 9.2.3.3 The UTL_RAW.BIT_OR function The BIT_OR function performs a bitwise logical OR of the two input raw strings r1 and r2. If r1 and r2 are of different length, the return value is the same length as the longer input string. The return value is the bitwise OR of the two inputs up to the length of the shorter input string, with the remaining length filled from the unprocessed data in the longer input string. If either input string is NULL, the return value is NULL. FUNCTION UTL_RAW.BIT_OR (r1 IN RAW ,r2 IN RAW) RETURN RAW; Parameters are summarized in the following table. Parameter Description r1 Raw string to OR with r2 r2 Raw string to OR with r1 9.2.3.3.1 Restrictions This program asserts the following purity level with the RESTRICT_REFERENCES pragma: PRAGMA RESTRICT_REFERENCES(BIT_OR, WNDS, RNDS, WNPS, RNPS); 9.2.3.3.2 Example To turn on a bit in a bit flag variable using a bitmask, or to merge bitmasks, you can use the BIT_OR function, as shown in the example from BIT_AND. 9.2.3.4 The UTL_RAW.BIT_XOR function The BIT_XOR function performs a bitwise logical XOR of the two input raw strings r1 and r2. If r1 and r2 are of different lengths, the return value is the same length as the longer input string. The return value is the bitwise XOR of the two inputs, up to the length of the shorter input string with the remaining length filled from the unprocessed data in the longer input string. If either input string is NULL, the return value is NULL. Here's the specification: FUNCTION UTL_RAW.BIT_XOR (r1 IN RAW ,r2 IN RAW) RETURN RAW; Parameters are summarized in the following table. Parameter Description r1 Raw string to XOR with r2 [Appendix A] What's on the Companion Disk? 9.2.3 The UTL_RAW Interface 450 . offer substantial disk savings over traditional Btree indexes. The Oracle kernel supports the bitwise AND function natively via the undocumented function BITAND(x,x),[1] but the other bitwise operations. offers facilities for manipulating raw data types that are not found elsewhere in the Oracle Server product. Oracle has a robust set of functions available for the structured datatypes RAW, CHARACTER,. datatypes to VARCHAR2 datatypes (as well as from VARCHAR2 to raw). The coercion operations supported by Oracle involving raw datatypes via the standard SQL functions are raw−to−hex and hex−to−raw; via