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 varchar 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.
The function string_output_string 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. http_rewrite can be used to flush a string output stream.
If a string output stream is passed to the function result the data stored in it is sent to the client.
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.)
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.
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.