Sybernet / Supplied Packages Reference Release 3.00 May 25, 2008

HTTP.TRANSLATE

The TRANSLATE package provides subprograms for translating strings between different character sets. Supported character sets include Ascii, EBCDIC, and Hexadecimal. Because 4-bit character strings are not supported in Oracle, all translations to Hexadecimal must occur with an even number of characters. This makes sense because it is impossible to assign one half of a byte to null.

You will also find two functions for URI Encoding and URI Decoding a string in this package. There are two other functions for encoding and decoding strings suitable for Javascript.

Summary of Subprograms

ASCIITOEBCDIC

ASCIITOHEX

EBCDICTOASCII

EBCDICTOHEX

HEXTOASCII

HEXTOEBCDIC

HTTPDECODE

HTTPENCODE

JSDECODE

JSENCODE

URLDECODE

URLENCODE

Subprogram ASCIITOEBCDIC

ASCIITOEBCDIC translates a string from Ascii to EBCDIC. This overloaded subprogram can be called as a function which accepts a string of Ascii characters and returns a string of EBCDIC characters or as a procedure which accepts a string of Ascii characters and passes them (after translation) to HTTP.WRITE.

Syntax 1

Function ASCIITOEBCDIC
(
    SRC                       IN  VARCHAR2
)
RETURN VARCHAR2;

Parameters

src

Syntax 2

Procedure ASCIITOEBCDIC
(
    SRC                       IN  VARCHAR2
)   ;

Parameters

src

Example

The following example illustrates how to call ASCIITOEBCDIC:

declare
    src varchar(10) := '0123456789';
begin
    http.translate.ebcdictoascii(http.translate.asciitoebcdic(src));
end;

Subprogram ASCIITOHEX

ASCIITOHEX translates a string from Ascii to Hexadecimal. This overloaded subprogram can be called as a function which accepts one Ascii character that returns its decimal value or as a procedure which accepts a variable length string that writes its Hexadecimal representation. The length of the output parameter is exactly one half of the input parameter. An exception is raised if the input paramter's length is not an even number.

Syntax 1

Function ASCIITOHEX
(
    C                         IN  CHAR
)
RETURN NUMBER;

Parameters

c

Syntax 2

Procedure ASCIITOHEX
(
    SRC                       IN  VARCHAR2
)   ;

Parameters

src

Example

The following example illustrates how to call ASCIITOHEX:

declare
    src varchar(20) := '30313233343536373839';
begin
    http.translate.asciitohex(src);
end;

Subprogram EBCDICTOASCII

EBCDICTOASCII translate a string from EBCDIC to Ascii. This overloaded subprogram can be called as a function which accepts a string of EBCDIC characters and returns a string of Ascii characters or as a procedure which accepts a string of EBCDIC characters and passes them (after translation) to HTTP.WRITE.

Syntax 1

Function EBCDICTOASCII
(
    SRC                       IN  VARCHAR2
)
RETURN CHAR;

Parameters

src

Syntax 2

Procedure EBCDICTOASCII
(
    SRC                       IN  VARCHAR2
)   ;

Parameters

src

Example

The following example illustrates how to call EBCDICTOASCII:

declare
    src varchar(10) := '0123456789';
begin
    http.translate.ebcdictoascii(http.translate.asciitoebcdic(src));
end;

Subprogram EBCDICTOHEX

EBCDICTOHEX translates a string from EBCDIC to Hexadecimal. This overloaded subprogram can be called as a function which accepts one EBCDIC character that returns its decimal value or as a procedure which accepts a variable length string.

Syntax 1

Function EBCDICTOHEX
(
    C                         IN  CHAR
)
RETURN NUMBER;

Parameters

c

Syntax 2

Procedure EBCDICTOHEX
(
    SRC                       IN  VARCHAR2
)   ;

Parameters

src

Example

The following example illustrates how to call EBCDICTOHEX:

declare
    src varchar(20) := '30313233343536373839';
begin
    http.translate.ebcdictohex(http.translate.asciitoebcdic(src));
end;

Subprogram HEXTOASCII

HEXTOASCII translates a string from Hexadecimal to Ascii. This overloaded subprogram can be called as a function which accepts a numeric value (0 through 15) that returns its corresponding Ascii character or as a procedure which accepts a variable length string that is translated to Ascii.

Syntax 1

Function HEXTOASCII
(
    I                         IN  NUMBER
)
RETURN CHAR;

Parameters

i

Syntax 2

Procedure HEXTOASCII
(
    SRC                       IN  VARCHAR2
)   ;

Parameters

src

Example

The following example illustrates how to call HEXTOASCII:

declare
    src varchar(12) := 'Hello World';
begin
    http.translate.hextoascii(src);
end;

Subprogram HEXTOEBCDIC

HEXTOEBCDIC translates a string from Hexadecimal to EBCDIC. This overloaded subprogram can be called as a function which accepts a numeric value (0 through 15) that returns its corresponding EBCDIC character or as a procedure which accepts a variable length string that is translated to EBCDIC.

Syntax 1

Function HEXTOEBCDIC
(
    I                         IN  NUMBER
)
RETURN CHAR;

Parameters

i

Syntax 2

Procedure HEXTOEBCDIC
(
    SRC                       IN  VARCHAR2
)   ;

Parameters

src

Example

The following example illustrates how to call HEXTOEBCDIC:

declare
    src varchar(10) := '9';
begin
    http.translate.ebcdictoascii(http.translate.hextoebcdic(src));
end;

Subprogram JSDECODE

JSDECODE decodes a JavaScript string. Special characters in JavaScript strings like tab characters and quotation marks must be escaped. This function decodes such strings.

Syntax

Function JSDECODE
(
    SRC                           VARCHAR2
)
RETURN VARCHAR2;

Parameters

src

Example

The following example illustrates how to call JSDECODE:

declare
    var varchar(30) := '\"This string is quoted\"';
begin
    http.write(http.translate.jsdecode(var));
end;

Subprogram JSENCODE

JSENCODE encodes a JavaScript string. Special characters in JavaScript strings like tab characters and quotation marks must be escaped. This function encodes such strings.

Syntax

Function JSENCODE
(
    SRC                           VARCHAR2
)
RETURN VARCHAR2;

Parameters

src

Example

The following example illustrates how to call JSENCODE:

declare
    var varchar(30) := '"This ''string'' is quoted"';
begin
    http.writeln
    (
        '<script>'
    ,   'var'
    ,   '    s = "' || http.translate.jsencode(var) || '"'
    ,   '    ;'
    ,   '    alert(s);'
    ,   '</script>'
    )   ;
end;

Subprogram URLDECODE

URLDECODE decodes a URI string. Special characters in URI's like tab characters and quotation marks must be escaped. This function decodes such strings. Letters and numbers are not special characters and do not require URI encoding, but this function will decode strings containing these characters as well.

Syntax

Function URLDECODE
(
    URL                           VARCHAR2
)
RETURN VARCHAR2;

Parameters

url

Example

The following example illustrates how to call URLDECODE:

declare
    var varchar(30) := '%22This string is quoted%22';
begin
    http.write(http.translate.urldecode(var));
end;

Subprogram HTTPDECODE

HTTPDECODE decodes an HTML string. These are strings that contain HTML escape sequences like " and ". If this function is unable to decode an escape sequence (because it is invalid), the sequence is left untouched.

Syntax

Function HTTPDECODE
(
    SRC                           VARCHAR2
)
RETURN VARCHAR2;

Parameters

src

Example

The following example illustrates how to call HTTPDECODE:

declare
    var varchar(30) := 'Hello World';
begin
    http.write(http.translate.httpdecode(var));
end;

Subprogram HTTPENCODE

HTTPENCODE encodes an HTML string. Although HTTPDECODE will decode any HTML escape sequence, this function encodes only a subset of all possible values. The reason for this is that in general use it isn't necessary to escape space characters, for example. What is escaped includes double-quotes, single-quotes, less-than and greater-than signs.

Syntax

Function HTTPENCODE
(
    SRC                           VARCHAR2
)
RETURN VARCHAR2;

Parameters

src

Example

The following example illustrates how to call HTTPENCODE:

declare
    var varchar(30) := '"Hello World"';
begin
    http.write(http.translate.httpdecode(var));
end;

Example

The following example illustrates a practical use of this function when invoking a javascript function that wants to pass the parameter NAME (containing, for example, double-quotes). In this example notice that we are in a single quoted string which contains a double-quoted string which then needs to escape the use of double-quotes inside of that string, and worst of all the parameter we are passing contains yet another double-quoted string:

declare
    name varchar(30) := 'Cleaver,Theodore "Beaver"';
begin
    http.javascript.script(true);
    http.writeln
    (
        'function displayEmployee(name)'
    ,   '{'
    ,   '    alert(name);'
    ,   '    return;'
    ,   '}'
    ,   'window.document.write("<a href=\"javascript:displayEmployee(''' || http.translate.httpencode(name) || ''');\">The Beaver</a>");'
    )   ;
    http.javascript.script(false);
end;

Subprogram URLENCODE

URLENCODE encodes a URI string. Special characters in URI's like tab characters and quotation marks must be escaped. This function encodes such strings. Letters and numbers are not special characters and do not require URI encoding.

Syntax

Function URLENCODE
(
    URL                           VARCHAR2
)
RETURN VARCHAR2;

Parameters

url

Example

The following example illustrates how to call URLENCODE:

declare
    var varchar(30) := '"This string is quoted"';
begin
    http.write(http.translate.urlencode(var));
end;

See Also