%SYN_ESCAPE_HANDLE

Escape characters in a string in a handle

WSupported on Windows
USupported on Unix
VSupported on OpenVMS
NSupported in Synergy .NET
 
status = %SYN_ESCAPE_HANDLE(handle, rules, length)

Return value

status

One of the following values:

0 = Successful

E_INVHDL = A memory handle whose length is 0 was passed

Arguments

handle

The memory handle that contains the string to escape. (D_HANDLE)

rules

The escape rules to use:

XML_RULES = Use XML escape rules.

HTTP_RULES = Use HTTP escape rules.

HTTPDATA_RULES = Use RFC 3986 escape rules.

length

The length of the string and, upon return, the length of the escaped text. (n)

Discussion

%SYN_ESCAPE_HANDLE enables you to escape certain characters in a string within a memory handle so that an XML or HTTP parser can process them properly.

The following table lists the characters that will be escaped in an XML string and their corresponding escape codes:

Escape Codes for Characters in XML Strings

Character

Description

Escape code

&

Ampersand

&

<

Less than sign

&lt;

>

Greater than sign

&gt;

'

Apostrophe

&apos;

"

Double quotation mark

&quot;

The following table lists the characters that will be escaped in an HTTP URI and their corresponding escape codes:

Escape Codes for Characters in a Memory Handle

Character

Description

Escape code (hex)

0-31 (decimal)

Unprintable characters

%00-%1F

127 (decimal)

Delete

%7F

128-255 (decimal)

Non-ASCII characters

%80-%FF

$

Dollar sign

%24

+

Plus sign

%2B

,

Comma

%2C

' '

Space

%20

"

Double quotation mark

%22

<

Less than sign

%3C

>

Greater than sign

%3E

#

Pound sign

%23

%

Percent

%25

{

Left curly brace

%7B

}

Right curly brace

%7D

|

Vertical bar

%7C

\

Backslash

%5C

^

Caret

%5E

~

Tilde

%7E

[

Left square bracket

%5B

]

Right square bracket

%5D

`

Accent

%60

HTTPDATA_RULES enables you to encrypt data parts of the URI without affecting unreserved characters in the URI. The unreserved characters are alpha, numeric, hyphen (-), period (.), underscore (_), and tilde (~); all other characters are escaped. For detailed information about URI syntax and RFC 3986 escape rules, see tools.ietf.org/htm/rfc3986#section-2.

See also

Examples

.include "DBLDIR:synxml.def"
record
    h           ,D_HANDLE
    len         ,i4
    i           ,i4
proc
    open(2,o,"tt:")
    h = %mem_proc(DM_ALLOC+DM_STATIC,25)
    ^m(h) = 'hey$+, \"<>#%{}|\\^~[]hey'
    len = %trimz(^m(h))
    i = %syn_escape_handle(h,HTTP_RULES,len)
    writes(2,^m(h))
    len = %trimz(^m(h))
    i = %syn_unescape_handle(h,HTTP_RULES,len)
    writes(2,^m(h))
    close(2)