1 PACKAGE utl_raw IS
2
3 ------------
4 -- OVERVIEW
5 --
6 -- This package provides SQL functions for raws that concat,
7 -- substr, etc. to/from raws. This package is necessary
8 -- because normal SQL functions do not operate on raws and
9 -- PL/SQL does not allow overloading between a raw and a char
10 -- datatype. Also included are routines which convert various
11 -- COBOL number formats to/from raws.
12
13 -- UTL_RAW is not specific to the database environment and may
14 -- actually be used in other environments as it exists here.
15 -- For this reason, the prefix UTL has been given to the package
16 -- instead of DBMS.
17
18 -------
19 -- USES
20 --
21 -- The are many possible uses for the raw functions. The
22 -- functionality allows a raw "record" to be composed
23 -- of many elements. By using the raw datatype, character
24 -- set conversion will not be performed keeping the raw in
25 -- its original format when being transferred via rpc.
26 -- The raw functions also give the ability to manipulate
27 -- binary data which was previously limited to the hextoraw
28 -- and rawtohex functions.
29
30 -------------
31 -- CONSTANTS
32 --
33 -- Define constants to control endianess behavior, used by
34 -- cast_to_binary_integer and cast_from_binary_integer
35 big_endian CONSTANT PLS_INTEGER := 1;
36 little_endian CONSTANT PLS_INTEGER := 2;
37 machine_endian CONSTANT PLS_INTEGER := 3;
38
39 ---------------------------
40 -- PROCEDURES AND FUNCTIONS
41
42 /*----------------------------------------------------------------*/
43 /* CONCAT */
44 /*----------------------------------------------------------------*/
45 FUNCTION concat(r1 IN RAW DEFAULT NULL,
46 r2 IN RAW DEFAULT NULL,
47 r3 IN RAW DEFAULT NULL,
48 r4 IN RAW DEFAULT NULL,
49 r5 IN RAW DEFAULT NULL,
50 r6 IN RAW DEFAULT NULL,
51 r7 IN RAW DEFAULT NULL,
52 r8 IN RAW DEFAULT NULL,
53 r9 IN RAW DEFAULT NULL,
54 r10 IN RAW DEFAULT NULL,
55 r11 IN RAW DEFAULT NULL,
56 r12 IN RAW DEFAULT NULL) RETURN RAW;
57 pragma RESTRICT_REFERENCES(concat, WNDS, RNDS, WNPS, RNPS);
58
59 -- Concatenate a set of 12 raws into a single raw. If the
60 -- concatenated size exceeds 32K, an error is returned.
61
62 -- Input parameters:
63 -- r1....r12 are the raw items to concatenate.
64
65 -- Defaults and optional parameters: None
66
67 -- Return value:
68 -- raw - containing the items concatenated.
69
70 -- Errors:
71 -- VALUE_ERROR exception raised (to be revised in a future release)
72 -- If the sum of the lengths of the inputs exceeds the maximum
73 -- allowable length for a RAW.
74
75 /*----------------------------------------------------------------*/
76 /* CAST_TO_RAW */
77 /*----------------------------------------------------------------*/
78 FUNCTION cast_to_raw(c IN VARCHAR2 CHARACTER SET ANY_CS) RETURN RAW;
79 pragma RESTRICT_REFERENCES(cast_to_raw, WNDS, RNDS, WNPS, RNPS);
80
81 -- Cast a varchar2 to a raw
82 -- This function converts a varchar2 represented using N data bytes
83 -- into a raw with N data bytes.
84 -- The data is not modified in any way, only its datatype is recast
85 -- to a RAW datatype.
86
87 -- Input parameters:
88 -- c - varchar2 or nvarchar2 to be changed to a raw
89
90 -- Defaults and optional parameters: None
91
92 -- Return value:
93 -- raw - containing the same data as the input varchar2 and
94 -- equal byte length as the input varchar2 and without a
95 -- leading length field.
96 -- null - if c input parameter was null
97
98 -- Errors:
99 -- None
100
101 /*----------------------------------------------------------------*/
102 /* CAST_TO_VARCHAR2 */
103 /*----------------------------------------------------------------*/
104 FUNCTION cast_to_varchar2(r IN RAW) RETURN VARCHAR2;
105 pragma RESTRICT_REFERENCES(cast_to_varchar2, WNDS, RNDS, WNPS, RNPS);
106
107 -- Cast a raw to a varchar2
108 -- This function converts a raw represented using N data bytes
109 -- into varchar2 with N data bytes.
110 -- NOTE: Once the value is cast to a varchar2, string
111 -- operations or server->client communication will assume
112 -- that the string is represented using the database's
113 -- character set. "Garbage" results are likely if these
114 -- operations are applied to a string that is actually
115 -- represented using some other character set.
116
117 -- Input parameters:
118 -- r - raw (without leading length field) to be changed to a
119 -- varchar2)
120
121 -- Defaults and optional parameters: None
122
123 -- Return value:
124 -- varchar2 - containing having the same data as the input raw
125 -- null - if r input parameter was null
126
127 -- Errors:
128 -- None
129
130 /*----------------------------------------------------------------*/
131 /* CAST_TO_NVARCHAR2 */
132 /*----------------------------------------------------------------*/
133 FUNCTION cast_to_nvarchar2(r IN RAW) RETURN NVARCHAR2;
134 pragma RESTRICT_REFERENCES(cast_to_nvarchar2, WNDS, RNDS, WNPS, RNPS);
135
136 -- Cast a raw to a nvarchar2
137 -- This function converts a raw represented using N data bytes
138 -- into nvarchar2 with N data bytes.
139 -- NOTE: Once the value is cast to a nvarchar2, string
140 -- operations or server->client communication will assume
141 -- that the string is represented using the database's
142 -- NCHAR character set. "Garbage" results are likely if these
143 -- operations are applied to a string that is actually
144 -- represented using some other character set.
145
146 -- Input parameters:
147 -- r - raw (without leading length field) to be changed to a
148 -- nvarchar2)
149
150 -- Defaults and optional parameters: None
151
152 -- Return value:
153 -- nvarchar2 - containing having the same data as the input raw
154 -- null - if r input parameter was null
155
156 -- Errors:
157 -- None
158
159 /*----------------------------------------------------------------*/
160 /* LENGTH */
161 /*----------------------------------------------------------------*/
162 FUNCTION length(r IN RAW) RETURN NUMBER;
163 pragma RESTRICT_REFERENCES(length, WNDS, RNDS, WNPS, RNPS);
164
165 -- Return the length in bytes of a raw r.
166
167 -- Input parameters:
168 -- r - the raw byte stream to be measured
169
170 -- Defaults and optional parameters: None
171
172 -- Return value:
173 -- number - equal to the current length of the raw.
174
175 -- Errors:
176 -- None
177
178 /*----------------------------------------------------------------*/
179 /* SUBSTR */
180 /*----------------------------------------------------------------*/
181 FUNCTION substr(r IN RAW,
182 pos IN BINARY_INTEGER,
183 len IN BINARY_INTEGER DEFAULT NULL) RETURN RAW;
184 pragma RESTRICT_REFERENCES(substr, WNDS, RNDS, WNPS, RNPS);
185
186 -- Return a substring portion of raw r beginning at pos for len bytes.
187 -- If pos is positive, substr counts from the beginning of r to find
188 -- the first byte. If pos is negative, substr counts backwards from the
189 -- end of the r. The value pos cannot be 0. If len is omitted,
190 -- substr returns all bytes to the end of r. The value len cannot be
191 -- less than 1.
192
193 -- Input parameters:
194 -- r - the raw byte-string from which a portion is extracted.
195 -- pos - the byte pisition in r at which to begin extraction.
196 -- len - the number of bytes from pos to extract from r (optional).
197
198 -- Defaults and optional parameters:
199 -- len - position pos thru to the end of r
200
201 -- Return value:
202 -- Portion of r beginning at pos for len bytes long
203 -- null - if r input parameter was null
204
205 -- Errors:
206 -- VALUE_ERROR exception raised (to be revised in a future release)
207 -- when pos = 0
208 -- when len < 0
209
210 /*----------------------------------------------------------------*/
211 /* TRANSLATE */
212 /*----------------------------------------------------------------*/
213 FUNCTION translate(r IN RAW,
214 from_set IN RAW,
215 to_set IN RAW) RETURN RAW;
216 pragma RESTRICT_REFERENCES(translate, WNDS, RNDS, WNPS, RNPS);
217
218 -- Translate the bytes in the input r raw according to the bytes
219 -- in the translation raws, from_set and to_set. If a byte
220 -- in r has a matching byte in from_set, then it is replaced by the
221 -- byte in the corresponding position in to_set, or deleted.
222 -- Bytes in r but undefined in from_set are copied to the result.
223 -- Only the first (leftmost) occurrence of a byte in from_set is
224 -- used, subsequent duplicates are not scanned and are ignored.
225 -- If to_set is shorter than from_set, the extra from_set bytes
226 -- have no translation correspondence and any bytes in r matching
227 -- such uncorresponded bytes are deleted from the result raw.
228
229 -- Noted difference from TRANSLITERATE:
230 -- translation raws have no defaults.
231 -- r bytes undefined in the to_set translation raw are deleted.
232 -- result raw may be shorter than input r raw.
233
234 -- Input parameters:
235 -- r - raw source byte-string to be translated
236 -- from_set - raw byte-codes to be translated, if present in r
237 -- to_set - raw byte-codes to which corresponding from_str bytes
238 -- are translated
239
240 -- Defaults and optional parameters: None
241
242 -- Return value:
243 -- raw - translated byte-string
244
245 -- Errors:
246 -- VALUE_ERROR exception raised (to be revised in a future release)
247 -- when r is null and/or has 0 length
248 -- when from_set is null and/or has 0 length
249 -- when to_set is null and/or has 0 length
250
251 /*----------------------------------------------------------------*/
252 /* TRANSLITERATE */
253 /*----------------------------------------------------------------*/
254 FUNCTION transliterate(r IN RAW,
255 to_set IN RAW DEFAULT NULL,
256 from_set IN RAW DEFAULT NULL,
257 pad IN RAW DEFAULT NULL) RETURN RAW;
258 pragma RESTRICT_REFERENCES(transliterate, WNDS, RNDS, WNPS, RNPS);
259
260 -- Transliterate the bytes in the input r raw according to the bytes
261 -- in the transliteration raws, from_set and to_set.
262 -- Successive bytes in r are looked-up in the from_set and, if not
263 -- found, copied unaltered to the result raw, or if found, replaced
264 -- in the result raw by either corresponding bytes in the to_set or
265 -- the pad byte when no correspondence exists.
266 -- Bytes in r but undefined in from_set are copied to the result.
267 -- Only the first (leftmost) occurrence of a byte in from_set is
268 -- used, subsequent duplicates are not scanned and are ignored.
269 -- The result raw is always the same length as r.
270 -- from_set and to_set may be of any length.
271 -- If the to_set is shorter than the from_set, then the pad byte is
272 -- placed in the result raw when a selected from_set byte has no
273 -- corresponding to_set byte (as if the to_set were extended to the
274 -- same length as the from_set with pad bytes).
275
276 -- Noted difference from TRANSLATE:
277 -- r bytes undefined in to_set are padded.
278 -- result raw is always same length as input r raw.
279
280 -- Input parameters:
281 -- r - raw input byte-string to be transliterated
282 -- from_set - raw byte-codes to be translated ,if present in r
283 -- to_set - raw byte-codes to which corresponding from_set bytes
284 -- are translated
285 -- pad - 1 byte used when to-set is shorter than the from_set
286
287 -- Defaults and optional parameters:
288 -- from_set - x'00 through x'ff.
289 -- to_set - to the null string and effectively extended
290 -- with pad to the length of from_set as necessary.
291 -- pad - x'00'.
292
293 -- Return value:
294 -- raw - transliterated byte-string
295
296 -- Errors:
297 -- VALUE_ERROR exception raised (to be revised in a future release)
298 -- when r is null and/or has 0 length
299
300 /*----------------------------------------------------------------*/
301 /* OVERLAY */
302 /*----------------------------------------------------------------*/
303 FUNCTION overlay(overlay_str IN RAW,
304 target IN RAW,
305 pos IN BINARY_INTEGER DEFAULT 1,
306 len IN BINARY_INTEGER DEFAULT NULL,
307 pad IN RAW DEFAULT NULL) RETURN RAW;
308 pragma RESTRICT_REFERENCES(overlay, WNDS, RNDS, WNPS, RNPS);
309
310 -- Overlay the specified portion of target raw with overlay raw,
311 -- starting from byte position pos of target and proceding for len
312 -- bytes.
313 -- If overlay has less than len bytes, it is extended to len bytes
314 -- using the pad byte. If overlay exceeds len bytes, the extra
315 -- bytes in overlay are ignored.
316 -- If len bytes beginning at position pos of target exceeds the
317 -- length of target, target will be extended to contain the entire
318 -- length of overlay.
319 -- len, if specified, must be => 0.
320 -- pos, if specified, must be => 1.
321 -- If pos exceeeds the length of target, target will be padded with
322 -- pad bytes to position pos, and then target is further extended
323 -- with overlay bytes.
324
325 -- Input parameters:
326 -- overlay_str - byte-string used to overlay target
327 -- target - byte-string which is to be overlayed
328 -- pos - position in target (numbered from 1) to start overlay
329 -- len - the number of target bytes to overlay
330 -- pad - pad byte used when overlay len exceeds overlay length
331 -- or pos exceeds target length.
332
333 -- Defaults and optional parameters:
334 -- pos - 1.
335 -- len - to the length of overlay.
336 -- pad - x'00'.
337
338 -- Return value:
339 -- raw - The target byte_string overlayed as specified
340
341 -- Errors:
342 -- VALUE_ERROR exception raised (to be revised in a future release)
343 -- when overlay is null and/or has 0 length
344 -- when target is missing or undefined
345 -- when length of target exceeds maximum length of a raw
346 -- when len < 0
347 -- when pos < 1
348
349 /*----------------------------------------------------------------*/
350 /* COPIES */
351 /*----------------------------------------------------------------*/
352 FUNCTION copies(r IN RAW,
353 n IN NUMBER) RETURN RAW;
354 pragma RESTRICT_REFERENCES(copies, WNDS, RNDS, WNPS, RNPS);
355
356 -- Return n copies of r concatenated together.
357
358 -- Input parameters:
359 -- r - raw to be copied
360 -- n - number of times to copy the raw (must be positive)
361
362 -- Defaults and optional parameters: None
363
364 -- Return value:
365 -- The raw copied n times.
366
367 -- Errors:
368 -- VALUE_ERROR exception raised (to be revised in a future release)
369 -- r is missing, null and/or 0 length
370 -- n < 1
371 -- when length of result exceeds maximum length of a raw
372
373 /*----------------------------------------------------------------*/
374 /* XRANGE */
375 /*----------------------------------------------------------------*/
376 FUNCTION xrange(start_byte IN RAW DEFAULT NULL,
377 end_byte IN RAW DEFAULT NULL) RETURN RAW;
378 pragma RESTRICT_REFERENCES(xrange, WNDS, RNDS, WNPS, RNPS);
379
380 -- Returns a raw containing all valid 1-byte encodings in succession
381 -- beginning with the value start_byte and ending with the value
382 -- end_byte.
383 -- If start_byte is greater than end_byte, the succession of
384 -- result bytes begin with start_byte, wrap thru 'FF'x to '00'x,
385 -- and end at end_byte.
386 -- If specified, start_byte and end_byte must be single byte raws.
387
388 -- Input parameters:
389 -- start_byte - beginning byte-code value of resulting sequence
390 -- end_byte - ending byte-code value of resulting sequence
391
392 -- Defaults and optional parameters:
393 -- start_byte - x'00'
394 -- end_byte - x'FF'
395
396 -- Return value:
397 -- raw - containing succession of 1-byte hexadecimal encodings
398
399 -- Errors:
400 -- None
401
402 /*----------------------------------------------------------------*/
403 /* REVERSE */
404 /*----------------------------------------------------------------*/
405 FUNCTION reverse(r IN RAW) RETURN RAW;
406 pragma RESTRICT_REFERENCES(reverse, WNDS, RNDS, WNPS, RNPS);
407
408 -- Reverse a byte sequence in raw r from end to end.
409 -- For example, x'0102F3' would be reversed into x'F30201' and
410 -- 'xyz' would be reversed into 'zyx'.
411 -- The result length is the same as the input raw length.
412
413 -- Input parameters:
414 -- r - raw to reverse
415
416 -- Defaults and optional parameters: None
417
418 -- Return value:
419 -- raw - containing the "reverse" of r
420
421 -- Errors:
422 -- VALUE_ERROR exception raised (to be revised in a future release)
423 -- when r is null and/or has 0 length
424
425 /*----------------------------------------------------------------*/
426 /* COMPARE */
427 /*----------------------------------------------------------------*/
428 FUNCTION compare(r1 IN RAW,
429 r2 IN RAW,
430 pad IN RAW DEFAULT NULL) RETURN NUMBER;
431 pragma RESTRICT_REFERENCES(compare, WNDS, RNDS, WNPS, RNPS);
432
433 -- Compares raw r1 against raw r2. Returns 0 if r1 and r2 are
434 -- identical, otherwise, returns the position of the first byte
435 -- from r1 that does not match r2.
436 -- If r1 and r2 differ in length, the shorter raw is extended on
437 -- the right with pad if necessary.
438 -- right with pad if necessary. The default pad byte is x'00'.
439
440 -- Input parameters:
441 -- r1 - 1st raw to be compared, may be null and/or 0 length
442 -- r2 - 2nd raw to be compared, may be null and/or 0 length
443 -- pad - byte to extend whichever of r1 or r2 is shorter
444
445 -- Defaults and optional parameters:
446 -- pad - x'00'
447
448 -- Return value:
449 -- number = 0 if raw byte strings are both null or identical; or,
450 -- = position (numbered from 1) of first mismatched byte
451
452 -- Errors:
453 -- None
454
455 /*----------------------------------------------------------------*/
456 /* CONVERT */
457 /*----------------------------------------------------------------*/
458 FUNCTION convert(r IN RAW,
459 to_charset IN VARCHAR2,
460 from_charset IN VARCHAR2) RETURN RAW;
461 pragma RESTRICT_REFERENCES(convert, WNDS, RNDS, WNPS, RNPS);
462
463 -- Convert raw r from character set from_charset to character set
464 -- to_charset and return the resulting raw.
465 -- Both from_charset and to_charset must be supported character sets
466 -- defined to the Oracle server.
467
468 -- Input parameters:
469 -- r - raw byte-string to be converted.
470 -- to_charset - name of NLS character set to which r is converted.
471 -- from_charset - name of NLS character set in which r is supplied.
472
473 -- Defaults and optional parameters: None
474
475 -- Return value:
476 -- raw - bytestring r converted according to the specified
477 -- character sets.
478
479 -- Errors:
480 -- VALUE_ERROR exception raised (to be revised in a future release)
481 -- r missing, null and/or 0 length
482 -- from_charset or to_charset missing, null and/or 0 length
483 -- from_charset or to_charset names invalid or unsupported
484
485 /*----------------------------------------------------------------*/
486 /* BIT_AND */
487 /*----------------------------------------------------------------*/
488 FUNCTION bit_and(r1 IN RAW,
489 r2 IN RAW) RETURN RAW;
490 pragma RESTRICT_REFERENCES(bit_and, WNDS, RNDS, WNPS, RNPS);
491
492 -- Perform bitwise logical "and" of the values in raw r1 with raw r2
493 -- and return the "anded" result raw.
494 -- If r1 and r2 differ in length, the "and" operation is terminated
495 -- after the last byte of the shorter of the two raws, and the
496 -- unprocessed portion of the longer raw is appended to the partial
497 -- result.
498 -- The result length equals the longer of the two input raws.
499
500 -- Input parameters:
501 -- r1 - raw to "and" with r2
502 -- r2 - raw to "and" with r1
503
504 -- Defaults and optional parameters: None
505
506 -- Return value:
507 -- raw - containing the "and" of r1 and r2
508 -- null - if either r1 or r2 input parameter was null
509
510 -- Errors:
511 -- None
512
513 /*----------------------------------------------------------------*/
514 /* BIT_OR */
515 /*----------------------------------------------------------------*/
516 FUNCTION bit_or(r1 IN RAW,
517 r2 IN RAW) RETURN RAW;
518 pragma RESTRICT_REFERENCES(bit_or, WNDS, RNDS, WNPS, RNPS);
519
520 -- Perform bitwise logical "or" of the values in raw r1 with raw r2
521 -- and return the "or'd" result raw.
522 -- If r1 and r2 differ in length, the "or" operation is terminated
523 -- after the last byte of the shorter of the two raws, and the
524 -- unprocessed portion of the longer raw is appended to the partial
525 -- result.
526 -- The result length equals the longer of the two input raws.
527
528 -- Input parameters:
529 -- r1 - raw to "or" with r2
530 -- r2 - raw to "or" with r1
531
532 -- Defaults and optional parameters: None
533
534 -- Return value:
535 -- raw - containing the "or" of r1 and r2
536 -- null - if either r1 or r2 input parameter was null
537
538 -- Errors:
539 -- None
540
541 /*----------------------------------------------------------------*/
542 /* BIT_XOR */
543 /*----------------------------------------------------------------*/
544 FUNCTION bit_xor(r1 IN RAW,
545 r2 IN RAW) RETURN RAW;
546 pragma RESTRICT_REFERENCES(bit_xor, WNDS, RNDS, WNPS, RNPS);
547
548 -- Perform bitwise logical "exclusive or" of the values in raw r1
549 -- with raw r2 and return the "xor'd" result raw.
550 -- If r1 and r2 differ in length, the "xor" operation is terminated
551 -- after the last byte of the shorter of the two raws, and the
552 -- unprocessed portion of the longer raw is appended to the partial
553 -- result.
554 -- The result length equals the longer of the two input raws.
555
556 -- Input parameters:
557 -- r1 - raw to "xor" with r2
558 -- r2 - raw to "xor" with r1
559
560 -- Defaults and optional parameters: None
561
562 -- Return value:
563 -- raw - containing the "xor" of r1 and r2
564 -- null - if either r1 or r2 input parameter was null
565
566 -- Errors:
567 -- None
568
569 /*----------------------------------------------------------------*/
570 /* BIT_COMPLEMENT */
571 /*----------------------------------------------------------------*/
572 FUNCTION bit_complement(r IN RAW) RETURN RAW;
573 pragma RESTRICT_REFERENCES(bit_complement, WNDS, RNDS, WNPS, RNPS);
574
575 -- Perform bitwise logical "complement" of the values in raw r
576 -- and return the "complement'ed" result raw.
577 -- The result length equals the input raw r length.
578
579 -- Input parameters:
580 -- r - raw to perform "complement" operation.
581
582 -- Defaults and optional parameters: None
583
584 -- Return value:
585 -- raw - which is the "complement" of r1
586 -- null - if r input parameter was null
587
588 -- Errors:
589 -- None
590
591 /*----------------------------------------------------------------*/
592 /* CAST_TO_NUMBER */
593 /*----------------------------------------------------------------*/
594 FUNCTION cast_to_number(r IN RAW) RETURN NUMBER;
595 pragma RESTRICT_REFERENCES(cast_to_number, WNDS, RNDS, WNPS, RNPS);
596
597 -- Perform a casting of the binary representation of the number (in RAW)
598 -- into a NUMBER.
599
600 -- Input parameters:
601 -- r - RAW value to be cast as a NUMBER
602
603 -- Return value:
604 -- number
605 -- null - if r input parameter was null
606
607 -- Errors:
608 -- None
609
610 /*----------------------------------------------------------------*/
611 /* CAST_FROM_NUMBER */
612 /*----------------------------------------------------------------*/
613 FUNCTION cast_from_number(n IN NUMBER) RETURN RAW;
614 pragma RESTRICT_REFERENCES(cast_from_number, WNDS, RNDS, WNPS, RNPS);
615
616
617 -- Returns the binary representation of a NUMBER in RAW.
618
619 -- Input parameters:
620 -- n - NUMBER to be returned as RAW
621
622 -- Return value:
623 -- raw
624 -- null - if n input parameter was null
625
626 -- Errors:
627 -- None
628
629 /*----------------------------------------------------------------*/
630 /* CAST_TO_BINARY_INTEGER */
631 /*----------------------------------------------------------------*/
632 FUNCTION cast_to_binary_integer(r IN RAW,
633 endianess IN PLS_INTEGER
634 DEFAULT 1)
635 RETURN BINARY_INTEGER;
636 pragma RESTRICT_REFERENCES(cast_to_binary_integer, WNDS, RNDS, WNPS, RNPS);
637
638 -- Perform a casting of the binary representation of the raw
639 -- into a binary integer. This function will handle PLS_INTEGER as well
640 -- as binary integer.
641 -- In the 4 byte, 2 byte, and 1 byte integer cases, here is how the
642 -- bytes are mapped into a RAW depending on the endianess of the platform:
643 --
644 -- 4-byte raw 2-byte raw 1-byte raw
645 -- 0 1 2 3 0 1 0
646 --
647 -- Big-endian 0 1 2 3 - - 0 1 - - - 0
648 --
649 -- Little-endian 3 2 1 0 - - 1 0 - - - 0
650 --
651 -- Machine-endian refers to the endianess of the database host and
652 -- can be either big or little endian. In this case, the bytes are
653 -- copied straight across into the integer value without endianess
654 -- handling.
655 --
656 -- Machine-endian-lze refers to treating the raw as an unsigned
657 -- quantity. This applies only in the 1,2,3-byte cases, as the
658 -- 4-byte case is forced to be signed by our binary_integer datatype.
659 -- In the case of a 4-byte input and machine-endian-lze, we will treat
660 -- this as a signed 4-byte quantity - the same as machine-endian.
661 --
662 -- Input parameters:
663 -- r - RAW value to be cast to binary integer
664 -- endianess - PLS_INTEGER representing endianess. Valid values are
665 -- big_endian,little_endian,machine_endian
666 -- Default=big_endian.
667
668 -- Defaults and optional parameters: endianess defaults to big_endian
669
670 -- Return value:
671 -- binary_integer value
672 -- null - if r input parameter was null
673
674 -- Errors:
675 -- None
676
677 /*----------------------------------------------------------------*/
678 /* CAST_FROM_BINARY_INTEGER */
679 /*----------------------------------------------------------------*/
680 FUNCTION cast_from_binary_integer(n IN BINARY_INTEGER,
681 endianess IN PLS_INTEGER
682 DEFAULT 1)
683 RETURN RAW;
684 pragma RESTRICT_REFERENCES(cast_from_binary_integer,WNDS,RNDS,WNPS,RNPS);
685
686 -- Return the RAW representation of a binary_integer value. This function
687 -- will handle PLS_INTEGER as well as binary integer. The mapping applies
688 -- as follows for little and big-endian platforms:
689 --
690 -- 4-byte int
691 -- 0 1 2 3
692 --
693 -- Big-endian 0 1 2 3
694 --
695 -- Little-endian 3 2 1 0
696 --
697
698 -- Input parameters:
699 -- n - binary integer to be returned as RAW
700 -- endianess - big or little endian PLS_INTEGER constant
701
702 -- Defaults and optional parameters: endianess defaults to big_endian
703
704 -- Return value:
705 -- raw
706 -- null - if n input parameter was null
707
708 -- Errors:
709 -- None
710
711 /*----------------------------------------------------------------*/
712 /* CAST_FROM_BINARY_FLOAT */
713 /*----------------------------------------------------------------*/
714 FUNCTION cast_from_binary_float(n IN BINARY_FLOAT,
715 endianess IN PLS_INTEGER
716 DEFAULT 1)
717 RETURN RAW;
718 pragma RESTRICT_REFERENCES(cast_from_binary_float,WNDS,RNDS,WNPS,RNPS);
719
720 -- Return the RAW representation of a binary_float value.
721 --
722 -- A 4-byte binary_float value maps to the the IEEE 754 single-precision
723 -- format as follows:
724 -- byte 0: bit 31 ~ bit 24
725 -- byte 1: bit 23 ~ bit 16
726 -- byte 2: bit 15 ~ bit 8
727 -- byte 3: bit 7 ~ bit 0
728 --
729 -- The parameter endianess describes how the bytes of binary_float are
730 -- mapped to the bytes of raw. In the following table, rb0 ~ rb3 refer
731 -- to the bytes in raw and fb0 ~ fb3 refer to the bytes in binary_float.
732 --
733 -- rb0 rb1 rb2 rb3
734 -- +----------------------+
735 -- big_endian |fb0 | fb1 | fb2 | fb3 |
736 -- |----------------------|
737 -- little_endian |fb3 | fb2 | fb1 | fb0 |
738 -- +----------------------+
739 --
740 -- In case of machine-endian, the 4 bytes of the binary_float argument
741 -- are copied straight across into the raw return value. The effect is
742 -- the same if the user has passed big_endian on a big endian machine,
743 -- or little_endian on a little endian machine.
744 --
745 -- Input parameters:
746 -- n - binary_float to be returned as RAW
747 -- endianess - big, little or machine endian PLS_INTEGER constant
748 --
749 -- Defaults and optional parameters: endianess defaults to big_endian
750 --
751 -- Return value:
752 -- raw
753 -- null - if n input parameter was null
754 --
755 -- Errors:
756 -- None
757
758
759 /*----------------------------------------------------------------*/
760 /* CAST_TO_BINARY_FLOAT */
761 /*----------------------------------------------------------------*/
762 FUNCTION cast_to_binary_float(r IN RAW,
763 endianess IN PLS_INTEGER
764 DEFAULT 1)
765 RETURN BINARY_FLOAT;
766 pragma RESTRICT_REFERENCES(cast_to_binary_float, WNDS, RNDS, WNPS, RNPS);
767
768 -- Perform a casting of the binary representation of the raw
769 -- into a binary_float.
770 --
771 -- A 4-byte binary_float value maps to the the IEEE 754 single-precision
772 -- format as follows:
773 -- byte 0: bit 31 ~ bit 24
774 -- byte 1: bit 23 ~ bit 16
775 -- byte 2: bit 15 ~ bit 8
776 -- byte 3: bit 7 ~ bit 0
777 --
778 -- The parameter endianess describes how the bytes of binary_float are
779 -- mapped to the bytes of raw. In the following table, rb0 ~ rb3 refer
780 -- to the bytes in raw and fb0 ~ fb3 refer to the bytes in binary_float.
781 --
782 -- rb0 rb1 rb2 rb3
783 -- +----------------------+
784 -- big_endian |fb0 | fb1 | fb2 | fb3 |
785 -- |----------------------|
786 -- little_endian |fb3 | fb2 | fb1 | fb0 |
787 -- +----------------------+
788 --
789 -- In case of machine-endian, the 4 bytes of the raw argument
790 -- are copied straight across into the binary_float return value.
791 -- The effect is the same if the user has passed big_endian on a
792 -- big endian machine, or little_endian on a little endian machine.
793 --
794 -- Input parameters:
795 -- r - RAW value to be cast to binary_float
796 -- endianess - big, little or machine endian PLS_INTEGER constant
797 --
798 -- Defaults and optional parameters: endianess defaults to big_endian
799 --
800 -- Note:
801 -- If the RAW argument is more than 4 bytes, only the first 4
802 -- bytes are used and the rest of the bytes are ignored. If the
803 -- result is -0, +0 is returned. If the result is NaN, the value
804 -- BINARY_FLOAT_NAN is returned.
805 --
806 -- Return value:
807 -- binary_float value
808 -- null - if r input parameter was null
809 --
810 -- Errors:
811 -- If the RAW argument is less than 4 bytes, VALUE_ERROR exception
812 -- is raised (to be revised in a future release).
813
814 /*----------------------------------------------------------------*/
815 /* CAST_FROM_BINARY_DOUBLE */
816 /*----------------------------------------------------------------*/
817 FUNCTION cast_from_binary_double(n IN BINARY_DOUBLE,
818 endianess IN PLS_INTEGER
819 DEFAULT 1)
820 RETURN RAW;
821 pragma RESTRICT_REFERENCES(cast_from_binary_double,WNDS,RNDS,WNPS,RNPS);
822
823 -- Return the RAW representation of a binary_double value.
824 --
825 -- An 8-byte binary_double value maps to the the IEEE 754 double-precision
826 -- format as follows:
827 -- byte 0: bit 63 ~ bit 56
828 -- byte 1: bit 55 ~ bit 48
829 -- byte 2: bit 47 ~ bit 40
830 -- byte 3: bit 39 ~ bit 32
831 -- byte 4: bit 31 ~ bit 24
832 -- byte 5: bit 23 ~ bit 16
833 -- byte 6: bit 15 ~ bit 8
834 -- byte 7: bit 7 ~ bit 0
835 --
836 -- The parameter endianess describes how the bytes of binary_double are
837 -- mapped to the bytes of raw. In the following table, rb0 ~ rb7 refer
838 -- to the bytes in raw and db0 ~ db7 refer to the bytes in binary_double.
839 --
840 -- rb0 rb1 rb2 rb3 rb4 rb5 rb6 rb7
841 -- +----------------------------------------------+
842 -- big_endian |db0 | db1 | db2 | db3 | db4 | db5 | db6 | db7 |
843 -- |----------------------------------------------|
844 -- little_endian |db7 | db6 | db5 | db4 | db3 | db2 | db1 | db0 |
845 -- +----------------------------------------------+
846 --
847 -- In case of machine-endian, the 8 bytes of the binary_double argument
848 -- are copied straight across into the raw return value. The effect is
849 -- the same if the user has passed big_endian on a big endian machine,
850 -- or little_endian on a little endian machine.
851 --
852 -- Input parameters:
853 -- n - binary_double to be returned as RAW
854 -- endianess - big, little or machine endian PLS_INTEGER constant
855 --
856 -- Defaults and optional parameters: endianess defaults to big_endian
857 --
858 -- Return value:
859 -- raw
860 -- null - if n input parameter was null
861 --
862 -- Errors:
863 -- None
864
865
866 /*----------------------------------------------------------------*/
867 /* CAST_TO_BINARY_DOUBLE */
868 /*----------------------------------------------------------------*/
869 FUNCTION cast_to_binary_double(r IN RAW,
870 endianess IN PLS_INTEGER
871 DEFAULT 1)
872 RETURN BINARY_DOUBLE;
873 pragma RESTRICT_REFERENCES(cast_to_binary_double, WNDS, RNDS, WNPS, RNPS);
874
875 -- Perform a casting of the binary representation of the raw
876 -- into a binary_double.
877 --
878 -- An 8-byte binary_double value maps to the the IEEE 754 double-precision
879 -- format as follows:
880 -- byte 0: bit 63 ~ bit 56
881 -- byte 1: bit 55 ~ bit 48
882 -- byte 2: bit 47 ~ bit 40
883 -- byte 3: bit 39 ~ bit 32
884 -- byte 4: bit 31 ~ bit 24
885 -- byte 5: bit 23 ~ bit 16
886 -- byte 6: bit 15 ~ bit 8
887 -- byte 7: bit 7 ~ bit 0
888 --
889 -- The parameter endianess describes how the bytes of binary_double are
890 -- mapped to the bytes of raw. In the following table, rb0 ~ rb7 refer
891 -- to the bytes in raw and db0 ~ db7 refer to the bytes in binary_double.
892 --
893 -- rb0 rb1 rb2 rb3 rb4 rb5 rb6 rb7
894 -- +----------------------------------------------+
895 -- big_endian |db0 | db1 | db2 | db3 | db4 | db5 | db6 | db7 |
896 -- |----------------------------------------------|
897 -- little_endian |db7 | db6 | db5 | db4 | db3 | db2 | db1 | db0 |
898 -- +----------------------------------------------+
899 --
900 -- In case of machine-endian, the 8 bytes of the raw argument
901 -- are copied straight across into the binary_double return value.
902 -- The effect is the same if the user has passed big_endian on a
903 -- big endian machine, or little_endian on a little endian machine.
904 --
905 -- Input parameters:
906 -- r - RAW value to be cast to binary_double
907 -- endianess - big, little or machine endian PLS_INTEGER constant
908 --
909 -- Defaults and optional parameters: endianess defaults to big_endian
910 --
911 -- Note:
912 -- If the RAW argument is more than 8 bytes, only the first 8
913 -- bytes are used and the rest of the bytes are ignored. If the
914 -- result is -0, +0 is returned. If the result is NaN, the value
915 -- BINARY_DOUBLE_NAN is returned.
916 --
917 -- Return value:
918 -- binary_double value
919 -- null - if r input parameter was null
920 --
921 -- Errors:
922 -- If the RAW argument is less than 8 bytes, VALUE_ERROR exception
923 -- is raised (to be revised in a future release).
924
925 /*----------------------------------------------------------------*/
926
927 END UTL_RAW;
[Home] [Help]