274 UTL_RAW
The UTL_RAW
package provides SQL functions for manipulating RAW
datatypes.
This chapter contains the following topics:
274.1 UTL_RAW Overview
This package is necessary because normal SQL functions do not operate on RAWs
, and PL/SQL does not allow overloading between a RAW
and a CHAR
datatype. UTL_RAW
also includes subprograms that convert various COBOL number formats to, and from, RAWs
.
UTL_RAW
is not specific to the database environment, and it may actually be used in other environments. For this reason, the prefix UTL has been given to the package, instead of DBMS.
274.2 UTL_RAW Operational Notes
UTL_RAW
allows a RAW
"record" to be composed of many elements. By using the RAW
datatype, character set conversion will not be performed, keeping the RAW
in its original format when being transferred through remote procedure calls.
With the RAW
functions, you can manipulate binary data that was previously limited to the hextoraw
and rawtohex
functions.
Note:
Notes on datatypes:
-
The
PLS_INTEGER
andBINARY_INTEGER
datatypes are identical. This document usesBINARY_INTEGER
to indicate datatypes in reference information (such as for table types, record types, subprogram parameters, or subprogram return values), but may use either in discussion and examples. -
The
INTEGER
andNUMBER(38)
datatypes are also identical. This document usesINTEGER
throughout.
274.3 Summary of UTL_RAW Subprograms
This table lists the UTL_RAW
subprograms and briefly describes them.
Table 274-1 UTL_RAW Package Subprograms
Subprogram | Description |
---|---|
Performs bitwise logical "and" of the values in |
|
Performs bitwise logical "complement" of the values in |
|
Performs bitwise logical "or" of the values in |
|
Performs bitwise logical "exclusive or" of the values in |
|
Returns the |
|
Returns the |
|
Returns the |
|
Returns the |
|
Casts the |
|
Casts the |
|
Casts the |
|
Casts the |
|
Converts a |
|
Converts a |
|
Converts a RAW value into a |
|
Compares |
|
Concatenates up to 12 |
|
Converts |
|
Returns |
|
Returns the length in bytes of a |
|
Overlays the specified portion of target |
|
Reverses a byte sequence in |
|
Returns |
|
Translates the bytes in the input |
|
Converts the bytes in the input |
|
Returns a |
274.3.1 BIT_AND Function
This function performs bitwise logical "and" of the values in RAW r1
with RAW r2
and returns the "anded" result RAW
.
Syntax
UTL_RAW.BIT_AND ( r1 IN RAW, r2 IN RAW) RETURN RAW;
Pragmas
pragma restrict_references(bit_and, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-2 BIT_AND Function Parameters
Parameter | Description |
---|---|
|
|
|
|
Return Values
Table 274-3 BIT_AND Function Return Values
Return | Description |
---|---|
|
Containing the "and" of |
|
Either |
Usage Notes
If r1
and r2 differ in length, the and operation is terminated after the last byte of the shorter of the two RAWs
, and the unprocessed portion of the longer RAW
is appended to the partial result. The result length equals the longer of the two input RAWs
.
274.3.2 BIT_COMPLEMENT Function
This function performs bitwise logical "complement" of the values in RAW r
and returns the complemented result RAW
. The result length equals the input RAW r
length.
Syntax
UTL_RAW.BIT_COMPLEMENT ( r IN RAW) RETURN RAW;
Pragmas
pragma restrict_references(bit_complement, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-4 BIT_COMPLEMENT Function Parameters
Parameter | Description |
---|---|
|
|
Return Values
Table 274-5 BIT_COMPLEMENT Function Return Values
Return | Description |
---|---|
|
The "complement" of |
|
If |
274.3.3 BIT_OR Function
This function performs bitwise logical "or" of the values in RAW r1
with RAW r2
and returns the or'd result RAW
.
Syntax
UTL_RAW.BIT_OR ( r1 IN RAW, r2 IN RAW) RETURN RAW;
Pragmas
pragma restrict_references(bit_or, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-6 BIT_OR Function Parameters
Parameters | Description |
---|---|
|
|
|
|
Return Values
Table 274-7 BIT_OR Function Return Values
Return | Description |
---|---|
|
Containing the "or" of |
|
Either |
Usage Notes
If r1
and r2
differ in length, then the "or" operation is terminated after the last byte of the shorter of the two RAWs
, and the unprocessed portion of the longer RAW
is appended to the partial result. The result length equals the longer of the two input RAWs
.
274.3.4 BIT_XOR Function
This function performs bitwise logical "exclusive or" of the values in RAW r1
with RAW r2
and returns the xor'd result RAW
.
Syntax
UTL_RAW.BIT_XOR ( r1 IN RAW, r2 IN RAW) RETURN RAW;
Pragmas
pragma restrict_references(bit_xor, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-8 BIT_XOR Function Parameters
Parameter | Description |
---|---|
|
|
|
|
Return Values
Table 274-9 BIT_XOR Function Return Values
Return | Description |
---|---|
|
Containing the "xor" of |
|
If either |
Usage Notes
If r1
and r2
differ in length, then the "xor" operation is terminated after the last byte of the shorter of the two RAWs
, and the unprocessed portion of the longer RAW
is appended to the partial result. The result length equals the longer of the two input RAWs
.
274.3.5 CAST_FROM_BINARY_DOUBLE Function
This function returns the RAW
binary representation of a BINARY_DOUBLE
value.
Syntax
UTL_RAW.CAST_FROM_BINARY_DOUBLE( n IN BINARY_DOUBLE, endianess IN PLS_INTEGER DEFAULT 1) RETURN RAW;
Pragmas
pragma restrict_references(cast_from_binary_double, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-10 CAST_FROM_BINARY_DOUBLE Function Parameters
Parameter | Description |
---|---|
|
|
|
A |
Return Values
The binary representation of the BINARY_DOUBLE
value, or NULL
if the input is NULL
.
Usage Notes
-
An 8-byte
binary_double
value maps to the IEEE 754 double-precision format as follows:byte 0: bit 63 ~ bit 56 byte 1: bit 55 ~ bit 48 byte 2: bit 47 ~ bit 40 byte 3: bit 39 ~ bit 32 byte 4: bit 31 ~ bit 24 byte 5: bit 23 ~ bit 16 byte 6: bit 15 ~ bit 8 byte 7: bit 7 ~ bit 0
-
The parameter endianess describes how the bytes of
BINARY_DOUBLE
are mapped to the bytes ofRAW
. In the following matrix, rb0 ~ rb7 refer to the bytes in raw and db0 ~ db7 refer to the bytes inBINARY_DOUBLE.
endianess rb0 rb1 rb2 rb3 rb4 rb5 rb6 rb7 big_endian
db0
db1
db2
db3
db4
db5
db6
db7
little_endian
db7
db6
db5
db4
db3
db2
db1
db0
-
In case of machine-endian, the 8 bytes of the
BINARY_DOUBLE
argument are copied straight across into theRAW
return value. The effect is the same if the user has passedbig_endian
on a big-endian machine, orlittle_endian
on a little-endian machine.
274.3.6 CAST_FROM_BINARY_FLOAT Function
This function returns the RAW
binary representation of a BINARY_FLOAT
value.
Syntax
UTL_RAW.CAST_FROM_BINARY_FLOAT( n IN BINARY_FLOAT, endianess IN PLS_INTEGER DEFAULT 1) RETURN RAW;
Pragmas
pragma restrict_references(cast_from_binary_float, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-11 CAST_FROM_BINARY_FLOAT Function Parameters
Parameter | Description |
---|---|
|
|
|
A |
Return Values
The binary representation (RAW) of the BINARY_FLOAT
value, or NULL
if the input is NULL
.
Usage Notes
-
A 4-byte
binary_float
value maps to the IEEE 754 single-precision format as follows:byte 0: bit 31 ~ bit 24 byte 1: bit 23 ~ bit 16 byte 2: bit 15 ~ bit 8 byte 3: bit 7 ~ bit 0
-
The parameter endianess describes how the bytes of
BINARY_FLOAT
are mapped to the bytes ofRAW
. In the following matrix, rb0 ~ rb3 refer to the bytes inRAW
and fb0 ~ fb3 refer to the bytes inBINARY_FLOAT
.Endianess rb0 rb1 rb2 rb3 big_endian
fb0
fb1
fb2
fb3
little_endian
fb3
fb2
fb1
fb0
-
In case of machine-endian, the 4 bytes of the
BINARY_FLOAT
argument are copied straight across into theRAW
return value. The effect is the same if the user has passedbig_endian
on a big-endian machine, orlittle_endian
on a little-endian machine.
274.3.7 CAST_FROM_BINARY_INTEGER Function
This function returns the RAW
binary representation of a BINARY_INTEGER
value.
Syntax
UTL_RAW.CAST_FROM_BINARY_INTEGER ( n IN BINARY_INTEGER endianess IN PLS_INTEGER DEFAULT BIG_ENDIAN) RETURN RAW;
Pragmas
pragma restrict_references(cast_from_binary_integer, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-12 CAST_FROM_BINARY_INTEGER Function Parameters
Parameter | Description |
---|---|
|
|
|
A |
Return Values
The binary representation of the BINARY_INTEGER
value.
274.3.8 CAST_FROM_NUMBER Function
This function returns the RAW
binary representation of a NUMBER
value.
Syntax
UTL_RAW.CAST_FROM_NUMBER ( n IN NUMBER) RETURN RAW;
Pragmas
pragma restrict_references(cast_from_number, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-13 CAST_FROM_NUMBER Function Parameters
Parameter | Description |
---|---|
|
|
Return Values
The binary representation of the NUMBER
value.
274.3.9 CAST_TO_BINARY_DOUBLE Function
This function casts the RAW binary representation of a BINARY_DOUBLE
into a BINARY_DOUBLE
.
Syntax
UTL_RAW.CAST_TO_BINARY_DOUBLE ( r IN RAW endianess IN PLS_INTEGER DEFAULT 1) RETURN BINARY_DOUBLE;
Pragmas
pragma restrict_references(cast_to_binary_double, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-14 CAST_TO_BINARY_DOUBLE Function Parameters
Parameter | Description |
---|---|
|
Binary representation of a |
|
A |
Return Values
The BINARY_DOUBLE
value.
Usage Notes
-
If the
RAW
argument is more than 8 bytes, only the first 8 bytes are used and the rest of the bytes are ignored. If the result is-0
,+0
is returned. If the result isNaN
, the valueBINARY_DOUBLE_NAN
is returned. -
If the
RAW
argument is less than 8 bytes, aVALUE_ERROR
exception is raised. -
An 8-byte binary_double value maps to the IEEE 754 double-precision format as follows:
byte 0: bit 63 ~ bit 56 byte 1: bit 55 ~ bit 48 byte 2: bit 47 ~ bit 40 byte 3: bit 39 ~ bit 32 byte 4: bit 31 ~ bit 24 byte 5: bit 23 ~ bit 16 byte 6: bit 15 ~ bit 8 byte 7: bit 7 ~ bit 0
-
The parameter endianess describes how the bytes of
BINARY_DOUBLE
are mapped to the bytes ofRAW
. In the following matrix, rb0 ~ rb7 refer to the bytes in raw and db0 ~ db7 refer to the bytes inBINARY_DOUBLE.
Architecture rb0 rb1 rb2 rb3 rb4 rb5 rb6 rb7 big_endian
db0
db1
db2
db3
db4
db5
db6
db7
little_endian
db7
db6
db5
db4
db3
db2
db1
db0
-
In case of machine-endian, the 8 bytes of the
RAW
argument are copied straight across into theBINARY_DOUBLE
return value. The effect is the same if the user has passedbig_endian
on a big-endian machine, orlittle_endian
on a little-endian machine.
274.3.10 CAST_TO_BINARY_FLOAT Function
This function casts the RAW binary representation of a BINARY_FLOAT
into a BINARY_FLOAT
.
Syntax
UTL_RAW.CAST_TO_BINARY_FLOAT ( r IN RAW endianess IN PLS_INTEGER DEFAULT 1) RETURN BINARY_FLOAT;
Pragmas
pragma restrict_references(cast_to_binary_float, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-15 CAST_TO_BINARY_FLOAT Function Parameters
Parameter | Description |
---|---|
|
Binary representation of a |
|
A |
Return Values
The BINARY_FLOAT
value.
Usage Notes
-
If the
RAW
argument is more than 4 bytes, only the first 4 bytes are used and the rest of the bytes are ignored. If the result is -0, +0 is returned. If the result is NaN, the valueBINARY_FLOAT_NAN
is returned. -
If the
RAW
argument is less than 4 bytes, aVALUE_ERROR
exception is raised. -
A 4-byte
binary_float
value maps to the IEEE 754 single-precision format as follows:byte 0: bit 31 ~ bit 24 byte 1: bit 23 ~ bit 16 byte 2: bit 15 ~ bit 8 byte 3: bit 7 ~ bit 0
-
The parameter endianess describes how the bytes of
BINARY_FLOAT
are mapped to the bytes ofRAW
. In the following matrix, rb0 ~ rb3 refer to the bytes inRAW
and fb0 ~ fb3 refer to the bytes inBINARY_FLOAT
.Endianness rb0 rb1 rb2 rb3 big_endian
fbo
fb1
fb2
fb3
little_endian
fb3
fb2
fb1
fb0
-
In case of machine-endian, the 4 bytes of the
RAW
argument are copied straight across into theBINARY_FLOAT
return value. The effect is the same if the user has passedbig_endian
on a big-endian machine, orlittle_endian
on a little-endian machine.
274.3.11 CAST_TO_BINARY_INTEGER Function
This function casts the RAW binary representation of a BINARY_INTEGER
into a BINARY_INTEGER
.
Syntax
UTL_RAW.CAST_TO_BINARY_INTEGER ( r IN RAW endianess IN PLS_INTEGER DEFAULT BIG_ENDIAN) RETURN BINARY_INTEGER;
Pragmas
pragma restrict_references(cast_to_binary_integer, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-16 CAST_TO_BINARY_INTEGER Function Parameters
Parameter | Description |
---|---|
|
Binary representation of a |
|
A |
Return Values
The BINARY_INTEGER
value
274.3.12 CAST_TO_NUMBER Function
This function casts the RAW binary representation of a NUMBER
into a NUMBER
.
Syntax
UTL_RAW.CAST_TO_NUMBER ( r IN RAW) RETURN NUMBER;
Pragmas
pragma restrict_references(cast_to_number, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-17 CAST_TO_NUMBER function Parameters
Parameter | Description |
---|---|
|
Binary representation of a |
Return Values
The NUMBER
value.
274.3.13 CAST_TO_NVARCHAR2 Function
This function converts a RAW
value represented using some number of data bytes into an NVARCHAR2
value with that number of data bytes.
Note:
When casting to a NVARCHAR2
, the current Globalization Support character set is used for the characters within that NVARCHAR2
value.
Syntax
UTL_RAW.CAST_TO_NVARCHAR2 ( r IN RAW) RETURN NVARCHAR2;
Pragmas
pragma restrict_references(cast_to_NVARCHAR2, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-18 CAST_TO_NVARCHAR2 Function Parameters
Parameter | Description |
---|---|
|
|
Return Values
Table 274-19 CAST_TO_NVARCHAR2 Function Return Values
Return | Description |
---|---|
|
Containing having the same data as the input |
|
If |
274.3.14 CAST_TO_RAW Function
This function converts a VARCHAR2
value represented using some number of data bytes into a RAW
value with that number of data bytes. The data itself is not modified in any way, but its datatype is recast to a RAW
datatype.
Syntax
UTL_RAW.CAST_TO_RAW ( c IN VARCHAR2) RETURN RAW;
Pragmas
pragma restrict_references(cast_to_raw, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-20 CAST_TO_RAW Function Parameters
Parameter | Description |
---|---|
|
|
Return Values
Table 274-21 CAST_TO_RAW Function Return Values
Return | Description |
---|---|
|
Containing the same data as the input |
|
If |
274.3.15 CAST_TO_VARCHAR2 Function
This function converts a RAW
value represented using some number of data bytes into a VARCHAR2
value with that number of data bytes.
Note:
When casting to a VARCHAR2
, the current Globalization Support character set is used for the characters within that VARCHAR2
.
Syntax
UTL_RAW.CAST_TO_VARCHAR2 ( r IN RAW) RETURN VARCHAR2;
Pragmas
pragma restrict_references(cast_to_VARCHAR2, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-22 CAST_TO_VARCHAR2 Function Parameters
Parameter | Description |
---|---|
|
|
Return Values
Table 274-23 CAST_TO_VARCHAR2 Function Return Values
Return | Description |
---|---|
|
Containing having the same data as the input |
|
If |
274.3.16 COMPARE Function
This function compares two RAW
values. If they differ in length, then the shorter is extended on the right according to the optional pad
parameter.
Syntax
UTL_RAW.COMPARE ( r1 IN RAW, r2 IN RAW, pad IN RAW DEFAULT NULL) RETURN NUMBER;
Pragmas
pragma restrict_references(compare, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-24 COMPARE Function Parameters
Parameter | Description |
---|---|
|
1st |
|
2nd |
|
This is an optional parameter. Byte to extend whichever of |
Return Values
Table 274-25 COMPARE Function Return Values
Return | Description |
---|---|
|
Equals 0 if Equals position (numbered from 1) of the first mismatched byte |
274.3.17 CONCAT Function
This function concatenates up to 12 RAWs
into a single RAW
. If the concatenated size exceeds 32K, then an error is returned
Syntax
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, r10 IN RAW DEFAULT NULL, r11 IN RAW DEFAULT NULL, r12 IN RAW DEFAULT NULL) RETURN RAW;
Pragmas
pragma restrict_references(concat, WNDS, RNDS, WNPS, RNPS);
Parameters
r1
....r12
are the RAW
items to concatenate.
Return Values
Table 274-26 CONCAT Function Return Values
Return | Description |
---|---|
|
Containing the items concatenated |
Exceptions
There is an error if the sum of the lengths of the inputs exceeds the maximum allowable length for a RAW
, which is 32767 bytes.
274.3.18 CONVERT Function
This function converts RAW
r
from character set from_charset
to character set to_charset
and returns the resulting RAW
.
Both from_charset
and to_charset
must be supported character sets defined to the Oracle server.
Syntax
UTL_RAW.CONVERT ( r IN RAW, to_charset IN VARCHAR2, from_charset IN VARCHAR2) RETURN RAW;
Pragmas
pragma restrict_references(convert, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-27 CONVERT Function Parameters
Parameter | Description |
---|---|
|
|
|
Name of the character set to which |
|
Name of the character set in which |
Return Values
Table 274-28 CONVERT Function Return Values
Return | Description |
---|---|
|
Byte string |
Exceptions
Table 274-29 CONVERT Function Exceptions
Error | Description |
---|---|
|
PL/SQL: numeric or value error |
|
This character set conversion is not supported |
|
Cannot access NLS data files or invalid environment specified |
Usage Notes
-
The NLS_LANG parameter form language_territory.character set is also accepted for
to_charset
andfrom_charset
. However, this form is deprecated and should be avoided. Note that language and territory are ignored by this subprogram. -
The converted value is silently truncated if it exceeds the maximum length of a
RAW
value, which is 32767 bytes. Do not convert values longer than floor(32767/4) = 8191 bytes if you want to avoid this truncation for all possible combinations ofto_charset
andfrom_charset
. You can use the maximum character width of the target character setto_charset
, if known, to expand the limit to a less pessimistic value. For example, if the target character set is ZHS16GBK, the maximum safe source string length is floor(32767/2) = 16383 bytes. For single-byte target character sets, no truncation is ever necessary.
274.3.19 COPIES Function
This function returns n
copies of r
concatenated together.
Syntax
UTL_RAW.COPIES ( r IN RAW, n IN NUMBER) RETURN RAW;
Pragmas
pragma restrict_references(copies, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-30 COPIES Function Parameters
Parameters | Description |
---|---|
|
|
|
Number of times to copy the |
Return Values
This returns the RAW
copied n
times.
Exceptions
Table 274-31 COPIES Function Exceptions
Error | Description |
---|---|
|
Either: - - - Length of result exceeds maximum length of a |
274.3.20 LENGTH Function
This function returns the length in bytes of a RAW r
.
Syntax
UTL_RAW.LENGTH ( r IN RAW) RETURN NUMBER;
Pragmas
pragma restrict_references(length, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-32 LENGTH Function Parameters
Parameter | Description |
---|---|
|
|
Return Values
Table 274-33 LENGTH Function Return Values
Return | Description |
---|---|
|
Current length of the |
274.3.21 OVERLAY Function
This function overlays the specified portion of target RAW
with overlay_str
RAW
, starting from byte position pos
of target
and proceeding for len
bytes.
Syntax
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;
Pragmas
pragma restrict_references(overlay, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-34 OVERLAY Function Parameters
Parameters | Description |
---|---|
|
Byte-string used to overlay target |
|
Byte-string which is to be overlaid |
|
Position in target (numbered from 1) to start overlay |
|
The number of target bytes to overlay |
|
Pad byte used when overlay |
Defaults and Optional Parameters
Table 274-35 OVERLAY Function Optional Parameters
Optional Parameter | Description |
---|---|
|
1 |
|
To the length of |
|
x'00' |
Return Values
Table 274-36 OVERLAY Function Return Values
Return | Description |
---|---|
|
The target |
Usage Notes
If overlay_str
has less than len
bytes, then it is extended to len
bytes using the pad
byte. If overlay_str
exceeds len
bytes, then the extra bytes in overlay_str
are ignored. If len
bytes beginning at position pos
of target
exceeds the length of target
, then target
is extended to contain the entire length of overlay_str
.
If
len
is specified, it must be greater than or equal to 0
. If pos
is specified, it must be greater than or equal to 1
. If pos
exceeds the length of target
, then target
is padded with pad
bytes to position pos
, and target
is further extended with overlay_str
bytes.
Exceptions
Table 274-37 OVERLAY Function Exceptions
Error | Description |
---|---|
|
Either: - - Target is missing or undefined - Length of target exceeds maximum length of a - - |
274.3.22 REVERSE Function
This function reverses a byte sequence in RAW r
from end to end.
For example, x'0102F3' would be reversed to x'F30201', and 'xyz' would be reversed to 'zyx'.The result length is the same as the input RAW
length.
Syntax
UTL_RAW.REVERSE ( r IN RAW) RETURN RAW;
Pragmas
pragma restrict_references(reverse, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-38 REVERSE Function Parameters
Parameter | Description |
---|---|
|
|
Return Values
Table 274-39 REVERSE Function Return Values
Return | Description |
---|---|
|
Containing the "reverse" of |
Exceptions
Table 274-40 REVERSE Function Exceptions
Error | Description |
---|---|
|
|
274.3.23 SUBSTR Function
This function returns len
bytes, starting at pos
from RAW
r
.
Syntax
UTL_RAW.SUBSTR ( r IN RAW, pos IN BINARY_INTEGER, len IN BINARY_INTEGER DEFAULT NULL) RETURN RAW;
Pragmas
pragma restrict_references(substr, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-41 SUBSTR Function Parameters
Parameter | Description |
---|---|
|
|
|
Byte position in |
|
Number of bytes from |
Defaults and Optional Parameters
Table 274-42 SUBSTR Function Optional Parameter
Optional Parameter | Description |
---|---|
|
Position |
Return Values
Table 274-43 SUBSTR Function Return Values
Return | Description |
---|---|
|
Beginning at |
|
|
Usage Notes
-
If
pos
is positive, thenSUBSTR
counts from the beginning ofr
to find the first byte. Ifpos
is negative, thenSUBSTR
counts backward from the end of ther
. The valuepos
cannot be 0. -
If
len
is omitted, thenSUBSTR
returns all bytes to the end ofr
. The valuelen
cannot be less than 1.
Exceptions
Table 274-44 SUBSTR Function Exceptions
Error | Description |
---|---|
|
|
274.3.24 TRANSLATE Function
This function translates the bytes in the input RAW r
according to the bytes in the translation RAWs from_set
and to_set
.
If a byte in r
has a matching byte in from_set
, then it is replaced by the byte in the corresponding position in to_set
, or deleted.
Bytes in r
, but undefined in from_set
, are copied to the result. Only the first (leftmost) occurrence of a byte in from_set
is used. Subsequent duplicates are not scanned and are ignored.
Syntax
UTL_RAW.TRANSLATE ( r IN RAW, from_set IN RAW, to_set IN RAW) RETURN RAW;
Note:
Be aware that to_set
and from_set
are reversed in the calling sequence compared to TRANSLITERATE
.
Pragmas
pragma restrict_references(translate, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-45 TRANSLATE Function Parameters
Parameter | Description |
---|---|
|
|
|
|
|
|
Return Values
Table 274-46 TRANSLATE Function Return Values
Return | Description |
---|---|
|
Translated byte-string |
Usage Notes
-
If
to_set
is shorter thanfrom_set
, the extrafrom_set
bytes have no corresponding translation bytes. Bytes from the inputRAW
that match any suchfrom_set
bytes are not translated or included in the result. They are effectively translated toNULL
. -
If
to_set
is longer thanfrom_set
, the extrato_set
bytes are ignored. -
If a byte value is repeated in
from_set
, the repeated occurrence is ignored.
Note:
Differences from the TRANSLITERATE Function:
-
The
from_set
parameter comes before theto_set
parameter in the calling sequence. -
Bytes from
r
that appear infrom_set
but have no corresponding values into_set
are not translated or included in the result. -
The resulting
RAW
value may be shorter than the inputRAW
value.
Note that TRANSLATE
and TRANSLITERATE
only differ in functionality when to_set
has fewer bytes than from_set
.
Exceptions
Table 274-47 TRANSLATE Function Exceptions
Error | Description |
---|---|
|
Either: - - - |
274.3.25 TRANSLITERATE Function
This function converts the bytes in the input RAW r
according to the bytes in the transliteration RAWs
from_set
and to_set
.
Successive bytes in r
are looked up in the from_set
, and, if not found, copied unaltered to the result RAW
. If found, then they are replaced in the result RAW
by either corresponding bytes in the to_set
, or the pad
byte when no correspondence exists.
Bytes in r
, but undefined in from_set
, are copied to the result. Only the first (leftmost) occurrence of a byte in from_set
is used. Subsequent duplicates are not scanned and are ignored. The result RAW
is always the same length as r
.
Syntax
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;
Note:
Be aware that to_set
and from_set
are reversed in the calling sequence compared to TRANSLATE
.
Pragmas
pragma restrict_references(transliterate, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-48 TRANSLITERATE Function Parameters
Parameter | Description |
---|---|
|
|
|
|
|
|
|
1 byte used when to-set is shorter than the |
Defaults and Optional Parameters
Table 274-49 TRANSLITERATE Function Optional Parameters
Optional Parameter | Description |
---|---|
|
To the |
|
|
|
|
Return Values
Table 274-50 TRANSLITERATE Function Return Values
Return | Description |
---|---|
|
Converted byte-string. |
Usage Notes
-
If
to_set
is shorter thanfrom_set
, the extrafrom_set
bytes have no corresponding conversion bytes. Bytes from the inputRAW
that match any suchfrom_set
bytes are converted in the result to the pad byte instead. -
If
to_set
is longer thanfrom_set
, the extrato_set
bytes are ignored. -
If a byte value is repeated in
from_set
, the repeated occurrence is ignored.
Note:
Differences from the TRANSLATE Function:
-
The
to_set
parameter comes before thefrom_set
parameter in the calling sequence. -
Bytes from
r
that appear infrom_set
but have no corresponding values into_set
are replaced by pad in the result. -
The resulting
RAW
value always has the same length as the inputRAW
value.
Note that TRANSLATE
and TRANSLITERATE
only differ in functionality when to_set
has fewer bytes than from_set
.
Exceptions
Table 274-51 TRANSLITERATE Function Exceptions
Error | Description |
---|---|
|
|
274.3.26 XRANGE Function
This function returns a RAW value
containing the succession of one-byte encodings beginning and ending with the specified byte-codes. The specified byte-codes must be single-byte RAW
values. If the start_byte
value is greater than the end_byte
value, then the succession of resulting bytes begins with start_byte
, wraps through x'FF'
back to x'00'
, then ends at end_byte
.
Syntax
UTL_RAW.XRANGE ( start_byte IN RAW DEFAULT NULL, end_byte IN RAW DEFAULT NULL) RETURN RAW;
Pragmas
pragma restrict_references(xrange, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 274-52 XRANGE Function Parameters
Parameters | Description |
---|---|
|
Beginning byte-code value of resulting sequence. The default is |
|
Ending byte-code value of resulting sequence. The default is |
Return Values
Table 274-53 XRANGE Function Return Values
Return | Description |
---|---|
|
Containing succession of 1-byte hexadecimal encodings |