$Sock Capture - Revision history

JALWiccan: Automatically generated page update

2018-09-21T00:00:30Z

Automatically generated page update

← Older revision		Revision as of 00:00, 21 September 2018
Line 1:		Line 1:
	{{DISPLAYTITLE:$Sock_Capture}}		{{DISPLAYTITLE:$Sock_Capture}}
	<span class="pageSubtitle">Change print capture setting</span>		<span class="pageSubtitle">Change print capture setting</span>
	<p class="warn"><b>Note: </b>~~Most Sirius~~ $functions have been deprecated in favor of Object Oriented		<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented
	methods. The OO equivalent for <var>$Sock_Capture</var> is the <var>[[Capture (Socket function)\|Capture]]</var> method.</p>		methods. The OO equivalent for <var>$Sock_Capture</var> is the <var>[[Capture (Socket function)\|Capture]]</var> method.</p>

JAL at 17:10, 10 October 2014

2014-10-10T17:10:16Z

Show changes

JAL at 17:32, 23 July 2013

2013-07-23T17:32:00Z

← Older revision		Revision as of 17:32, 23 July 2013
Line 2:		Line 2:
	<span class="pageSubtitle">Change print capture setting</span>		<span class="pageSubtitle">Change print capture setting</span>
	<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented		<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented
	methods. ~~There is currently no direct~~ OO equivalent for ~~this~~ $function.</p>		methods. The OO equivalent for <var>$Sock_Capture</var> is the <var>[[Capture (Socket function)\|Capture]]</var> method.</p>

	<var>$Sock_Capture</var> specifies whether print output should be sent as lines on a <var class="product">Janus Sockets</var> connection.		<var>$Sock_Capture</var> specifies whether print output should be sent as lines on a <var class="product">Janus Sockets</var> connection.

JALWiccan: Automatically generated page update

2013-07-19T18:59:22Z

Automatically generated page update

← Older revision		Revision as of 18:59, 19 July 2013
Line 1:		Line 1:
	{{DISPLAYTITLE:$Sock_Capture}}		{{DISPLAYTITLE:$Sock_Capture}}
	<span class="pageSubtitle">Change print capture setting</span>		<span class="pageSubtitle">Change print capture setting</span>
	<p class="~~warning~~">Most Sirius $functions have been deprecated in favor of Object Oriented		<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented
	methods. There is currently no direct OO equivalent for this $function.</p>		methods. There is currently no direct OO equivalent for this $function.</p>

JAL: /* Print capturing hierarchy and other considerations */

2012-10-19T00:21:00Z

Print capturing hierarchy and other considerations

← Older revision		Revision as of 00:21, 19 October 2012
Line 65:		Line 65:
	<tr><th>COMMxx</th>		<tr><th>COMMxx</th>
	<td>If the thread was started by a Sirius $COMMxx function, the output can be saved in a [[$lists\|$list]] that can be processed by the $COMMxx caller. </td></tr>		<td>If the thread was started by a Sirius $COMMxx function, the output can be saved in a [[$lists\|$list]] that can be processed by the $COMMxx caller. </td></tr>
	<tr><th>Janus SDS, OPENSERV, or SRVSOCK</th>
			<tr><th nowrap>Janus SDS, OPENSERV, or SRVSOCK</th>
	<td>For an [[JANUS DEFINE#type\|SDS, OPENSERV, or SRVSOCK]] thread, the audit trail is used as the terminal output. For these port types, messages during compilation are always sent to the audit trail. For other types of print output, the <var class="product">Model 204</var> <var>AUDTERM</var> or <var>NOAUDTERM</var> parameter controls whether the terminal output is sent to the audit trail (<var>AUDTERM</var>) or simply discarded (<var>NOAUDTERM</var>). </td></tr>		<td>For an [[JANUS DEFINE#type\|SDS, OPENSERV, or SRVSOCK]] thread, the audit trail is used as the terminal output. For these port types, messages during compilation are always sent to the audit trail. For other types of print output, the <var class="product">Model 204</var> <var>AUDTERM</var> or <var>NOAUDTERM</var> parameter controls whether the terminal output is sent to the audit trail (<var>AUDTERM</var>) or simply discarded (<var>NOAUDTERM</var>). </td></tr>

	<tr><th>Janus Web</th>		<tr><th>Janus Web</th>
	<td>For a <var>[[JANUS DEFINE#type\|WEB]]</var> thread, the terminal output can either be the browser (if <var>[[$Web_On]]</var> is in effect) or the audit trail (if <var>[[$Web_Off]]</var> is in effect), although <var>NOAUDTERM</var> prevents non-compiler print lines from appearing on the audit trail, as with other Janus server threads. </td></tr>		<td>For a <var>[[JANUS DEFINE#type\|WEB]]</var> thread, the terminal output can either be the browser (if <var>[[$Web_On]]</var> is in effect) or the audit trail (if <var>[[$Web_Off]]</var> is in effect), although <var>NOAUDTERM</var> prevents non-compiler print lines from appearing on the audit trail, as with other Janus server threads. </td></tr>

JAL2: /* Syntax */

2012-01-20T02:55:28Z

Syntax

← Older revision		Revision as of 02:55, 20 January 2012
Line 7:		Line 7:

	==Syntax==		==Syntax==
	<p class="syntax"><span class="squareb">[</span><span class="term">%num</span><span class="literal"> =</span><span class="squareb">]</span><span class="literal">$Sock_Capture(</span><span class="term">sockNum</span><span class="literal">,</span><span class="term"> value</span><span class="literal">)</span> </p>		<p class="syntax"><span class="squareb">[</span><span class="term">%num</span><span class="literal"> =</span><span class="squareb">]</span> <span class="literal">$Sock_Capture(</span><span class="term">sockNum</span><span class="literal">,</span><span class="term"> value</span><span class="literal">)</span> </p>

Admin: 1 revision

2012-01-20T02:53:45Z

1 revision

← Older revision	Revision as of 02:53, 20 January 2012
(No difference)

JAL at 01:12, 20 January 2012

2012-01-20T01:12:22Z

New page

{{DISPLAYTITLE:$Sock_Capture}}
<span class="pageSubtitle">Change print capture setting</span>
<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented
methods. There is currently no direct OO equivalent for this $function.</p>

<var>$Sock_Capture</var> specifies whether print output should be sent as lines on a <var class="product">Janus Sockets</var> connection.

==Syntax==
<p class="syntax"><span class="squareb">[</span><span class="term">%num</span><span class="literal"> =</span><span class="squareb">]</span><span class="literal">$Sock_Capture(</span><span class="term">sockNum</span><span class="literal">,</span><span class="term"> value</span><span class="literal">)</span> </p>

===Syntax terms===
<table class="syntaxTable">
<tr><th>%num</th>
<td>The content of this return string depends on the <var class="term">sockNum</var> argument, as described below in [[#$Sock_Capture return values|"$Sock_Capture return values]]. </td></tr>
<tr><th>sockNum</th>
<td>The socket number, or it is '-1' to indicate that the setting affects all sockets.</td></tr>
<tr><th>value</th>
<td>A string that is the print capture setting for the socket. Valid values are:
<dl>
<dt>OFF<dd>Don't capture print to this socket.
<dt>ON<dd>Capture print to this socket as well as any other capturing sockets.
</dl></td></tr>
</table>

===$Sock_Capture return values===
<ul>
<li>If the <var class="term">sockNum</var> argument is -1, indicating that all sockets are affected by the <var>$Sock_Capture</var> call, the return string is the number of sockets (not counting the open sockets that have sent the <code>FIN</code> operation).
<li>If <var class="term">sockNum</var> is not -1, the returned string contains the value of the socket's previous <var>$Sock_Capture</var> setting.
<li>If a single socket is specified as the <var class="term">sockNum</var> value, the socket is not open,
and <var>ONRESET CONTINUE</var> is in effect for the socket, then <var>$Sock_Capture</var> returns the string <code>RESET</code>.
</ul>

==Usage notes==
<ul>
<li>Each captured print line is followed by a <var>LINEND</var> string,
if the socket has one set in its definition or by <var>[[$Sock_Set]]</var>.

<li>The set of socket numbers that currently capture print lines can be obtained as <code>$Sock_Num('CAPTURE')</code>.
The set of open socket numbers that currently capture print lines can be obtained as <code>$Sock_Num('CAPOPEN')</code>.

<li>When a <code>FIN</code> is sent (using either <var>[[$Sock_Send]]</var> or <var>[[$Sock_SendLn]]</var>), print capturing is automatically turned <var>OFF</var> for the socket.
</ul>

==Example==
In the following example, the <var>$Sock_Capture</var> call specifies that print operations should be sent to the [[JANUS SRVSOCK|SRVSOCK]] socket.
Subsequent print operations, such as the <var class="product">User Language</var> <var>Print</var> statement, will send lines to the socket rather than to the normal terminal output:
<p class="code">%t = $Sock_Capture(1, 'ON')
</p>

There is a more complete example in [[Sample Janus Sockets programs#Print capturing example|"Print capturing example"]]; also
see [[#Print capturing hierarchy and other considerations|"Print capturing hierarchy and other considerations"]].

==Print capturing hierarchy and other considerations==
The <var class="product">User Language</var> <var>Print</var> and <var>[[Text and Html statements|Html]]</var> statements, the <var>DISPLAY PROCEDURE</var> command, and the <var>DISPLAY LIST</var> command are a few of many "print"
operations that can produce output lines for an application.
These operations "normally" send their output to the "terminal output" for the thread running the application.
'''Terminal output''' refers to the print destination defined by the <var>IODEV</var> for the thread.

For example, the terminal output of an IODEV=7 (VTAM) terminal user is the user's 3270-style terminal; the
terminal output of an IODEV=29 (IFDIAL, or BATCH2) user is the MVS batch program that retrieves the output lines.

The terminal output of an <var>[[Sdaemons|Sdaemon]]</var> thread (usually IODEV=15) depends on how the <var>Sdaemon</var> was started:
<table>
<tr><th>COMMxx</th>
<td>If the thread was started by a Sirius $COMMxx function, the output can be saved in a [[$lists|$list]] that can be processed by the $COMMxx caller. </td></tr>
<tr><th>Janus SDS, OPENSERV, or SRVSOCK</th>
<td>For an [[JANUS DEFINE#type|SDS, OPENSERV, or SRVSOCK]] thread, the audit trail is used as the terminal output. For these port types, messages during compilation are always sent to the audit trail. For other types of print output, the <var class="product">Model 204</var> <var>AUDTERM</var> or <var>NOAUDTERM</var> parameter controls whether the terminal output is sent to the audit trail (<var>AUDTERM</var>) or simply discarded (<var>NOAUDTERM</var>). </td></tr>
<tr><th>Janus Web</th>
<td>For a <var>[[JANUS DEFINE#type|WEB]]</var> thread, the terminal output can either be the browser (if <var>[[$Web_On]]</var> is in effect) or the audit trail (if <var>[[$Web_Off]]</var> is in effect), although <var>NOAUDTERM</var> prevents non-compiler print lines from appearing on the audit trail, as with other Janus server threads. </td></tr>
</table>

As stated, $COMMxx can be used to process print output, since the <var>Sdaemon</var> doing its work can place print output in a Sirius $list.
There are also facilities for processing print output on any kind of
thread, including other <var>Sdaemon</var> threads, and 3270 and <var>IFDIAL</var>/<var>BATCH204</var> threads:
<ol>
<li>The <var>[[$List_Capture]]</var> function directs print output to a Sirius $list.
<li>The <var>$Sock_Capture</var> function directs print output to a <var class="product">Janus Sockets</var> connection.
<li>The <var class="product">Model 204</var> <var>USE</var> command directs print output to a <var>USE</var> stream.
</ol>

For the above three facilities, "interactive" output is not sent to the $list, the socket,
nor the <var>USE</var> stream, but instead is sent to the normal terminal output.
The types of interactive output lines are:
<table>
<tr><th><i>Type</i></th><th><i>Description</i></th></tr>
<tr><th>Messages</th>
<td>Informational or error messages (for example, M204.nnnn or MSIR.nnnn) except when <code>$List_Capture(id, 'MSGS')</code> in effect. </td></tr>
<tr><th>Prompts</th>
<td>Password prompts, <var>$Read</var> input, etc. </td></tr>
<tr><th>READ SCREEN</th>
<td><var class="product">User Language</var> full-screen display for input (note that <var>Print Screen</var> statements '''are subject''' to redirection) </td></tr>
<tr><th nowrap>WRITE IMAGE ON TERMINAL</th>
<td><var class="product">User Language</var> statement for sending lines directly to the normal terminal output </td></tr>
</table>

When an output line is redirected from the normal terminal output, it is directed based on the following hierarchy:
<table>
<tr><th><i>Type</i></th><th><i>Conditions</i></th></tr>
<tr><th>$List_Capture</th>
<td>Non-interactive print lines captured on $list, if one is active as specified to <var>$List_Capture</var> </td></tr>
<tr><th>$Sock_Capture</th>
<td>Non-interactive print lines captured on one or more sockets, if any are specified as <code>ON</code> to <var>$Sock_Capture</var>, and if no $list is active as specified to <var>$List_Capture</var> (<code>$List_Capture(-1)</code> removes any active $list capture) </td></tr>
<tr><th>USE stream</th>
<td>Non-interactive print lines directed to a <var>USE</var> stream, if it is active and there is no socket specified as <code>ON</code> to <var>$Sock_Capture</var> (<code>$Sock_Capture(-1, 'OFF')</code> removes all socket capturing)
and if no $list is active as specified to <var>$List_Capture</var> </td></tr>
<tr><th>Normal terminal output</th>
<td>Print lines are sent to the normal terminal output if none of the above print redirections are active </td></tr>
</table>

Below are some additional suggestions and considerations for the use of applications using print redirection in general and socket capturing in particular:
<ul>
<li>For output lines (non <var>SCREEN</var> output/input)
that should go to the terminal, use <var>WRITE IMAGE ON TERMINAL</var> (on server applications, where the "terminal" output is the audit trail, you can use <var>AUDIT</var> instead).

<li>In versions of <var class="product">Sirius Mods</var> prior to 6.4,
the capturing of print lines respects the <var class="product">Model 204</var> <var>OUTCCC</var>, <var>OUTMRL</var>, and
<var>LOBUFF</var> parameter formatting.
That is, a print line longer than <var>OUTCCC</var> wraps, and it is captured as an additional line for each time that it wraps.
A print line longer than <var>OUTMRL</var> or <var>LOBUFF</var> is truncated at <var>OUTMRL</var> or <var>LOBUFF</var> bytes, respectively.
<p>
As of version 6.4 of <var class="product">Sirius Mods</var>, the <var>OUTCCC</var>, <var>OUTMRL</var>, and <var>LOBUFF</var> limits are ignored for <var>$Sock_Capture</var>.
A very long print line is captured as a single "logical" line (with a single trailing <var>LINEND</var> string, as specified on the <var>[[JANUS DEFINE]]</var> command or <var>[[$Sock_Set]]</var> for the socket). </p>

<li>Output lines sent by the "ellipsis" form of the <var>Print</var> statement
(<code>PRINT <items> ...</code>) are captured without a trailing <var>LINEND</var> string.
The <var>LINEND</var> string is sent at the end of the logical line (that is, <var>OUTMRL</var>, <var>OUTCCC</var>, and <var>LOBUFF</var> do not cause added <var>LINEND</var> strings to be sent). The <var>LINEND</var> string is not translated.

<li>If the socket's <var>LINEND</var> parameter is <code>NONE</code> when a print line is captured, the line is simply sent without any string following it.

<li>If the socket is set to <var>CHAR</var>, the print line is translated using the output translation table specified
by the socket's <var>XTAB</var> parameter.
If the socket is set to <var>BINARY</var>, the print line is not translated.

<li>If you want a request to continue normal evaluation if a <code>RESET</code> condition is encountered on a socket,
use <code>$Sock_Set(socknum, 'ONRESET', 'CONTINUE')</code>.
When print capturing is attempted to an <var>ONRESET CONTINUE</var> socket, and the socket is
<code>RESET</code>, <var class="product">Janus Sockets</var> simply acts as if the print was captured and continues.

<li>If <var>CONTINUE</var> is not in effect for a <var>CAPTURE ON SOCKET</var> that is <code>RESET</code>,
a <var class="product">User Language</var> print operation will jump
to the <code>ONRESET</code> label if one is active, or else the
request is cancelled (and any <var>APSY</var> <var>ERROR</var> procedure is evaluated).
In this case, <var>[[$Sock_ErrInfo]]</var> returns -1 for <code>CODE</code>, and it returns the string
<code>Captured print</code> for <code>FUN</code>.
</ul>

[[Category: Janus Sockets $functions]]