Top

Name

string_output — make a string output stream

Synopsis

string_output ( in threshold integer );
 

Description

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.)

Parameters

threshold

Optional size threshold, exceeding this the object will be stored in a temp directory specified by 'TempSesDir' INI parameter.

Examples

Example 24.407. Handling string output streams

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.

Prev  Up  Next
stringtime   Home  string_output_flush