1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
-
- This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
- project.
-
- Copyright (C) 1998-2018 OpenLink Software
-
- This project is free software; you can redistribute it and/or modify it
- under the terms of the GNU General Public License as published by the
- Free Software Foundation; only version 2 of the License, dated June 1991.
-
- This program is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License for more details.
-
- You should have received a copy of the GNU General Public License along
- with this program; if not, write to the Free Software Foundation, Inc.,
- 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
-
-
-->
<refentry id="fn_http_value">
<refmeta>
<refentrytitle>http_value</refentrytitle>
<refmiscinfo>ws</refmiscinfo>
</refmeta>
<refnamediv>
<refname>http_value</refname>
<refpurpose>write to HTTP client or string output stream with HTML
escapes</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="fsyn_http_value">
<funcprototype id="fproto_http_value">
<funcdef><function>http_value</function></funcdef>
<paramdef>in <parameter>val_expr</parameter>any</paramdef>
<paramdef><optional>in <parameter>tag</parameter> varchar</optional></paramdef>
<paramdef><optional>in <parameter>stream</parameter> any</optional></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="desc_http_value"><title>Description</title>
<para>The <function>http_value</function> is used to write to an HTTP
client (when in a VSP context) or a specified string output stream.
<function>http_value</function> uses HTML-escapes for characters that
should be escaped according to the HTML spec.</para>
</refsect1>
<refsect1 id="params_http_value"><title>Parameters</title>
<refsect2><title>val_expr</title>
<para>A value expression. May be any string expression. If
<parameter>val_expr</parameter> is an XML entity, a serialization of
the entity is written to the <parameter>stream</parameter>. This is not
the string value of the XML fragment, but a serialization of the XML
fragment as text including all the markup, i.e. elements, attributes,
namespaces, text nodes, etc. To get the string value of an XML entity,
convert it to a varchar using <function>cast</function>. Casting as
varchar will only produce a concatenation of the text nodes in the
XML fragment, leaving out elements, attributes, name spaces, etc.</para>
</refsect2>
<refsect2><title>tag</title>
<para>Optional. If present and is a string, the output will be enclosed
in tags named as the string content of <parameter>tag</parameter>.
If the expression evaluates to 0 or null, it will be ignored.</para>
</refsect2>
<refsect2><title>stream</title>
<para>Optional parameter. If omitted or is 0 and the function is
executed within a VSP context, the <parameter>val_expr</parameter> will
be written to the HTTP client. If present and non-zero,
<parameter>val_expr</parameter> will be written to the specified stream.
If non-zero, the value must be a valid stream obtained
from function
<link linkend="fn_string_output"><function>string_output</function>
</link></para>
</refsect2>
</refsect1>
<refsect1 id="ret_http_value"><title>Return Values</title>
<para>None</para>
</refsect1>
<refsect1 id="errors_http_value"><title>Errors</title>
<table><title>Errors signalled by <function>http_value</function></title>
<tgroup cols="4">
<thead>
<row>
<entry>SQLSTATE</entry><entry>Error Code</entry><entry>Error Text</entry><entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><errorcode>37000</errorcode></entry>
<entry><errorcode>HT006</errorcode></entry>
<entry><errorname>http output function outside of http context
and no stream specified: %s</errorname></entry>
<entry>occurs if called outside VSP and no string session is
given </entry>
</row>
<row>
<entry><errorcode>22023</errorcode></entry>
<entry><errorcode>SR066</errorcode></entry>
<entry><errorname>Unsupported case in CONVERT
(<data_type_of 1st arg> -> VARCHAR): %s</errorname></entry>
<entry>if the value passed as the 1st argument can't be
converted to a VARCHAR value and it's not a XML/XQUERY tree
</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1 id="examples_http_value"><title>Using http_value()</title>
<example id="ex_http_value"><title>HTTP output</title>
<para>Output of various flavours of <function>http</function>. See
<link linkend="fn_string_output"><function>string_output</function>
</link> and
<link linkend="fn_string_output_string"><function>string_output_string
</function></link> for examples how to use http to write to streams
other than the HTTP output.</para>
<screen>
http (' % <b>') ' <b>
http_value (' % <b>') % &lt;b&gt;
http_url (' % <b>') +%25+<b>
http_value (12, 'li') <li>12</li>
</screen>
</example>
</refsect1>
<refsect1 id="seealso_http_value"><title>See Also</title>
<para>
<link linkend="fn_http"><function>http</function></link>,
<link linkend="fn_http_url"><function>http_url</function></link>,
<link linkend="fn_string_output"><function>string_output</function></link>,
<link linkend="fn_http_rewrite"><function>http_rewrite</function></link>.
</para>
</refsect1>
</refentry>
|
