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
|
<?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_flush">
<refmeta>
<refentrytitle>http_flush</refentrytitle>
<refmiscinfo>ws</refmiscinfo>
</refmeta>
<refnamediv>
<refname>http_flush</refname>
<refpurpose>Flush internal HTTP stream and disconnect client; Flush HTTP stream and try sending data in chunked mode.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="fsyn_http_flush">
<funcprototype id="fproto_http_flush">
<funcdef><function>http_flush</function></funcdef>
<paramdef><optional>in <parameter>try_what</parameter> integer</optional></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="desc_http_flush"><title>Description</title>
<para>
This flushes the internal buffer where output of a VSP page is stored pending the execution of the page's code.
This sends the content of the page output buffer along with headers and disconnects
the client. The status is 200 OK by default, unless overridden by http_status.
The purpose of this function is to allow a page to send output before terminating
, thus the page can continue processing for an indefinite time without
requiring the client to wait. This is useful for starting long running background tasks
from HTTP clients.
</para>
<para>
VSP pages that use this function must be sure to supply appropriate content
(or response headers) if needed before calling this function.
</para>
<para>Virtuoso supports HTTP 1.1 Chunking Encoding which allows Virtuoso to
send the user agent chunks of output as the page is still processing. Chunking
is enabled by calling <function>http_flush(1)</function> within the VSP page.
By default chunks are sent for every 4k worth of output generated, but in some
cases the output needs to consist of smaller chunks, for example when run-time status needs to be shown in a status page.
So to achieve this the http_flush (try_what=1) could be invoked
in places where chunk must be flushed to the User agent. </para>
<para>Chunked mode requires the following conditions:</para>
<simplelist>
<member>no "Content-Length" header sent to the client using http_header()</member>
<member>no "Content-Encoding" header sent to the client using http_header()</member>
<member>use http_xslt() is not permitted</member>
<member>The client supports HTTP 1.1</member>
</simplelist>
<para>Failing these conditions, <function>http_flush(1)</function> will be a
No-Operation.</para>
<para>If the function has actually switched to chunked mode it will return a non-zero integer. Otherwise
and integer 0 will be returned.</para>
<para>Chunked mode is not supported for static content.</para>
</refsect1>
<refsect1 id="params_http_flush"><title>Parameters</title>
<refsect2><title>try_what</title>
<para>This optional parameter can be supplied the value one (1) to instruct
Virtuoso to try sending the output of the VSP page in chunked mode.</para>
</refsect2>
</refsect1>
<refsect1 id="examples_http_flush"><title>Examples</title>
<example id="ex_http_flush"><title>Using http_flush()</title>
<programlisting>
<?vsp
http ('<p>Hit <a href="status.vsp">there</a> to go on status page</p>');
http_flush ();
long_task_procedure ();
?>
</programlisting>
</example>
<example id="ex_http_flush"><title>Using http_flush() small chunks</title>
<para>The following example will render in browser at every loop iteration
'state=N'; so this will be visible at 'run-time' not when loop finished which
may take a long.</para>
<programlisting><![CDATA[
<?vsp
....
http_flush (1);
while (i<1000)
{
process_some_item (); -- some procedure that takes a long time usually
http ('state='||cast (i as varchar)||'<br>');
http_flush (1);
i := i + 1;
}
?>]]>
</programlisting>
</example>
</refsect1>
<refsect1 id="seealso_http_flush"><title>See Also</title>
<para>
<link linkend="fn_http"><function>http</function></link>,
<link linkend="fn_http_value"><function>http_value</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>
|
