# 22. Virtuoso Functions Guide - string_output

Chapter Contents | Prev | Next
Keyword Search:
www.openlinksw.com
docs.openlinksw.com
Book Home
Contents
Preface
Virtuoso Functions Guide
Administration
Aggregate Functions
Array Manipulation
BPEL APIs
Backup
Compression
Cursor
Date & Time Manipulation
Debug
Dictionary Manipulation
Encoding & Decoding
File Manipulation
Free Text
Hashing / Cryptographic
LDAP
Locale
Mail
Miscellaneous
Number
Remote SQL Data Source
Replication
SOAP
SQL
String
ascii
atoi
blob_to_string
blob_to_string_outpu...
chr
initcap
isblob
isstring
lcase
left
length
locate
ltrim
make_string
regexp_instr
regexp_like
regexp_match
regexp_parse
regexp_replace
regexp_substr
repeat
replace
right
rtrim
search_excerpt
serialize
space
split_and_decode
sprintf
strcasestr
strchr
string_output
string_output_flush
string_output_gz_com...
string_output_string
string_to_file
strrchr
strstr
subseq
substring
tmp_file_name
trim
ucase
upper
Transaction
Type Mapping
UDDI
User Defined Types & The CLR
Virtuoso Java PL API
Virtuoso Server Extension Interface (VSEI)
Web Server & Internet
XML
XPATH & XQUERY
Functions Index

## string_output

make a string output stream
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
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.

See Also

string_output_stream, http, http_value