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
136
|
<?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_string_output">
<refmeta>
<refentrytitle>string_output</refentrytitle>
<refmiscinfo>string</refmiscinfo>
</refmeta>
<refnamediv>
<refname>string_output</refname>
<refpurpose>make a string output stream</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="fsyn_string_output">
<funcprototype id="fproto_string_output">
<funcdef><function>string_output</function></funcdef>
<paramdef><optional>in <parameter>threshold</parameter> integer</optional></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="desc"><title>Description</title>
<para>A string output stream is a special object that may be used to
buffer arbitrarily long streams of data. They are useful for handling data
that would not otherwise fit within normal <type>varchar</type> size
limitations. The HTTP output functions optionally take a string output
stream handle as a parameter and then output to said stream instead of
the HTTP client. A string output stream can be assigned to a database column in insert or update, causing the characters written to the stream to be assigned to the column as a narrow string.
</para>
<para>The function
<link linkend="fn_string_output_string"><function>string_output_string
</function></link>
can be used to produce a varchar out of a string output stream. It may
be called repeatedly to obtain several copies of the data.
<link linkend="fn_http_rewrite"><function>http_rewrite</function></link>
can be used to flush a string output stream.</para>
<para>If a string output stream is passed to the function
<link linkend="fn_result"><function>result</function></link> the
data stored in it is sent to the client.</para>
<para>The string output object cannot be copied. It cannot therefore be
assigned between two variables or passed by value (as an IN parameter.)
It can be passed by reference (OUT, INOUT parameter.)</para>
</refsect1>
<refsect1 id="params_string_output">
<title>Parameters</title>
<refsect2><title>threshold</title>
<para>Optional size threshold, exceeding this the object will be
stored in a temp directory specified by 'TempSesDir' INI parameter.</para>
</refsect2>
</refsect1>
<refsect1 id="examples"><title>Examples</title>
<example id="ex_string_output"><title>Handling string output streams</title>
<para>This example takes a string as an argument, creates a new string output stream, writes the string into the stream and inserts stream contents to a DB table.</para>
<screen>
create table
foo_table (
a integer identity,
b long varchar,
primary key (a));
create procedure
foo_out (in x varchar)
{
declare str_out any;
declare str varchar;
-- Pass correct result metadata to client
result_names (str);
-- Get a new string output stream
str_out := string_output();
http (x, str_out);
-- These produce the same result
result (string_output_string (str_out));
result (str_out);
-- insert string output contents
insert into foo_table (b) values (str_out);
-- Write it again to the string output
http (concat (' ', x), str_out);
result (str_out);
}
;
SQL> foo_out ('Ceterum censeo, Carthaginem esse delendum!');
str
VARCHAR NOT NULL
_______________________________________________________________________________
Ceterum censeo, Carthaginem esse delendum!
Ceterum censeo, Carthaginem esse delendum!
Ceterum censeo, Carthaginem esse delendum! Ceterum censeo, Carthaginem esse delendum!
2 Rows. -- 2 msec.
SQL> select * from foo_table;
a b
INTEGER NOT NULL LONG VARCHAR
_______________________________________________________________________________
1 Ceterum censeo, Carthaginem esse delendum!
1 Rows. -- 2 msec.
</screen>
</example>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para><link linkend="fn_string_output_string">
<function>string_output_stream</function></link>,
<link linkend="fn_http"><function>http</function></link>,
<link linkend="fn_http_value"><function>http_value</function></link></para>
</refsect1>
</refentry>
|
