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
|
<?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_ses_read_line">
<refmeta>
<refentrytitle>ses_read_line</refentrytitle>
<refmiscinfo>ws</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ses_read_line</refname>
<refpurpose>Read a line of character data from a TCP session.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="fsyn_ses_read_line">
<funcprototype id="fproto_ses_read_line">
<funcdef>varchar <function>ses_read_line</function></funcdef>
<paramdef><optional>in <parameter>ses</parameter> any</optional></paramdef>
<paramdef><optional>in <parameter>throw_exception_on_eof</parameter> integer</optional></paramdef>
<paramdef><optional>in <parameter>binary_mode</parameter>integer </optional></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="desc_ses_read_line">
<title>Description</title>
<para>This function is used to read a line of character data from an open TCP
session. This function will read characters until it reaches an end of line
up to a maximum of 1024 characters. The session can be passed as a
session_handle. If the session_handle is omitted then execution is in
current session/VSP context and will read from the open HTTP session.
<function>Ses_read_line()</function> will suspend execution while attempting
to read from the session until the timeout period of 100 seconds expires.
When the timeout expires an error will be produced to indicate that the
operation was unsuccessful.</para>
</refsect1>
<refsect1 id="params_ses_read_line">
<title>Parameters</title>
<refsect2><title>ses</title>
<para>Optional session handle. If none is supplied the current
TCP client session is assumed. If this is NULL then the function will
read from the string session to be sent to the client upon request completion.</para>
</refsect2>
<refsect2><title>throw_exception_on_eof</title>
<para>Controls whether to throw an error if there is a problem reading
from the session or simply return null in text mode or what ever content has
has been read so far in binary mode. If this parameter is set to 1, then
an error will be thrown. If this parameter is set to 0 then either null or remaining
content will be returned as above.</para>
</refsect2>
<refsect2><title>binary_mode</title>
<para>Instructs the function to be in binary or text mode.</para>
<simplelist>
<member>Binary mode: the function reads a maximum of 1024 bytes and
returns as much as it read as a varchar.</member>
<member>Text mode: the function reads up to 0x0A, it will trim all the
[0x0A|0x0D] characters at the end of the string and return it as varchar.</member>
</simplelist>
</refsect2>
</refsect1>
<refsect1 id="ret_ses_read_line"><title>Return Types</title>
<para>The characters read from the session are returned from this function.</para>
</refsect1>
<!--
<refsect1 id="errors_ses_read_line">
<title>Errors</title>
<table>
<title>Errors signalled by</title>
<tgroup cols="4">
<thead>
<row>
<entry>SQLState</entry>
<entry>Error Code</entry>
<entry>Error Text</entry>
<entry>Description</entry></row></thead>
<tbody>
<row>
<entry><errorcode></errorcode></entry>
<entry><errorcode></errorcode></entry>
<entry><errorname></errorname></entry>
<entry></entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
-->
<refsect1 id="examples_ses_read_line">
<title>Examples</title>
<example id="ex_ses_read_line"><title>Simple demonstration of reading from the HTTP session</title>
<para>This example reads the first line of the session and outputs the contents.
This code can be run from a vsp file.</para>
<screen><![CDATA[
<p>Some text</p>
<?vsp
declare xx any;
xx := ses_read_line (NULL);
http (sprintf ('length is %d, "%s"', length (xx), xx));
?>
]]>
</screen>
</example>
</refsect1>
<refsect1 id="seealso_ses_read_line">
<title>See Also</title>
<para><link linkend="fn_ses_connect"><function>ses_connect()</function></link></para>
<para><link linkend="fn_ses_disconnect"><function>ses_disconnect()</function></link></para>
<para><link linkend="fn_ses_write"><function>ses_write()</function></link></para>
</refsect1>
</refentry>
|
