$Sock Capture: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
(Automatically generated page update)
 
(One intermediate revision by one other user not shown)
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>


Line 13: Line 13:
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%num</th>
<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>  
<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>  
<tr><th>sockNum</th>  
<td>The socket number, or it is '-1' to indicate that the setting affects all sockets.</td></tr>  
<td>The socket number, or it is '-1' to indicate that the setting affects all sockets.</td></tr>  
<tr><th>value</th>  
<tr><th>value</th>  
<td>A string that is the print capture setting for the socket. Valid values are:
<td>A string that is the print capture setting for the socket. Valid values are:
Line 26: Line 28:
===$Sock_Capture return values===
===$Sock_Capture return values===
<ul>
<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 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>
<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 <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>
 
<li>If a single socket is specified as the <var class="term">sockNum</var> value, the socket is not open,
<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>.
and <var>ONRESET CONTINUE</var> is in effect for the socket, then <var>$Sock_Capture</var> returns the string <code>RESET</code>.
Line 49: Line 53:
</p>
</p>


There is a more complete example in [[Sample Janus Sockets programs#Print capturing example|"Print capturing example"]]; also
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"]].
see [[#Print capturing hierarchy and other considerations|Print capturing hierarchy and other considerations]].


==Print capturing hierarchy and other considerations==
==Print capturing hierarchy and other considerations==
Line 62: Line 66:


The terminal output of an <var>[[Sdaemons|Sdaemon]]</var> thread (usually IODEV=15) depends on how the <var>Sdaemon</var> was started:
The terminal output of an <var>[[Sdaemons|Sdaemon]]</var> thread (usually IODEV=15) depends on how the <var>Sdaemon</var> was started:
<table>
<table class="thJustBold">
<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>
Line 77: Line 81:
thread, including other <var>Sdaemon</var> threads, and 3270 and <var>IFDIAL</var>/<var>BATCH204</var> threads:
thread, including other <var>Sdaemon</var> threads, and 3270 and <var>IFDIAL</var>/<var>BATCH204</var> threads:
<ol>
<ol>
<li>The <var>[[$List_Capture]]</var> function directs print output to a Sirius $list.
<li>The <var>[[$List_Capture]]</var> function directs print output to a $list.
<li>The <var>$Sock_Capture</var> function directs print output to a <var class="product">Janus Sockets</var> connection.
<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.
<li>The <var class="product">Model 204</var> <var>USE</var> command directs print output to a <var>USE</var> stream.
Line 85: Line 89:
nor the <var>USE</var> stream, but instead is sent to the normal terminal output.
nor the <var>USE</var> stream, but instead is sent to the normal terminal output.
The types of interactive output lines are:
The types of interactive output lines are:
<table>
<table class="thJustBold">
<tr><th><i>Type</i></th><th><i>Description</i></th></tr>
<tr class="head"><th>Type</th><th>Description</th></tr>
 
<tr><th>Messages</th>
<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>
<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>
<tr><th>Prompts</th>
<td>Password prompts, <var>$Read</var> input, etc. </td></tr>
<td>Password prompts, <var>$Read</var> input, etc. </td></tr>
<tr><th>READ SCREEN</th>
<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>
<td><var class="product">SOUL</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>
<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>
<td><var class="product">SOUL</var> statement for sending lines directly to the normal terminal output </td></tr>
</table>
</table>


When an output line is redirected from the normal terminal output, it is directed based on the following hierarchy:
When an output line is redirected from the normal terminal output, it is directed based on the following hierarchy:
<table>
<table class="thJustBold">
<tr><th><i>Type</i></th><th><i>Conditions</i></th></tr>
<tr class="head"><th>Type</th><th>Conditions</th></tr>
 
<tr><th>$List_Capture</th>
<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>
<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>
<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>
<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>
<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)
<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>
and if no $list is active as specified to <var>$List_Capture</var> </td></tr>
<tr><th>Normal terminal output</th>
 
<tr><th nowrap>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>
<td>Print lines are sent to the normal terminal output if none of the above print redirections are active </td></tr>
</table>
</table>
Line 114: Line 126:
<ul>
<ul>
<li>For output lines (non <var>SCREEN</var> output/input)
<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).
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>


<li>In versions of <var class="product">Sirius Mods</var> prior to 6.4,
<li>The <var>OUTCCC</var>, <var>OUTMRL</var>, and <var>LOBUFF</var> limits are ignored for <var>$Sock_Capture</var>.
the capturing of print lines respects the <var class="product">Model 204</var> <var>OUTCCC</var>, <var>OUTMRL</var>, and
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). </li>
<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
<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.
(<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.
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>


<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'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>


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


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


<li>If <var>CONTINUE</var> is not in effect for a <var>CAPTURE ON SOCKET</var> that is <code>RESET</code>,
<li>If <var>CONTINUE</var> is not in effect for a <var>CAPTURE ON SOCKET</var> that is <code>RESET</code>,
Line 145: Line 151:
request is cancelled (and any <var>APSY</var> <var>ERROR</var> procedure is evaluated).
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
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>.
<code>Captured print</code> for <code>FUN</code>. </li>
</ul>
</ul>


[[Category: Janus Sockets $functions]]
[[Category: Janus Sockets $functions]]

Latest revision as of 00:00, 21 September 2018

Change print capture setting

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for $Sock_Capture is the Capture method.

$Sock_Capture specifies whether print output should be sent as lines on a Janus Sockets connection.

Syntax

[%num =] $Sock_Capture(sockNum, value)


Syntax terms

%num The content of this return string depends on the sockNum argument, as described below in $Sock_Capture return values.
sockNum The socket number, or it is '-1' to indicate that the setting affects all sockets.
value A string that is the print capture setting for the socket. Valid values are:
OFF
Don't capture print to this socket.
ON
Capture print to this socket as well as any other capturing sockets.

$Sock_Capture return values

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

Usage notes

  • Each captured print line is followed by a LINEND string, if the socket has one set in its definition or by $Sock_Set.
  • The set of socket numbers that currently capture print lines can be obtained as $Sock_Num('CAPTURE'). The set of open socket numbers that currently capture print lines can be obtained as $Sock_Num('CAPOPEN').
  • When a FIN is sent (using either $Sock_Send or $Sock_SendLn), print capturing is automatically turned OFF for the socket.

Example

In the following example, the $Sock_Capture call specifies that print operations should be sent to the SRVSOCK socket. Subsequent print operations, such as the User Language Print statement, will send lines to the socket rather than to the normal terminal output:

%t = $Sock_Capture(1, 'ON')

There is a more complete example in Print capturing example; also see Print capturing hierarchy and other considerations.

Print capturing hierarchy and other considerations

The User Language Print and Html statements, the DISPLAY PROCEDURE command, and the DISPLAY LIST 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 IODEV 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 Sdaemon thread (usually IODEV=15) depends on how the Sdaemon was started:

COMMxx If the thread was started by a Sirius $COMMxx function, the output can be saved in a $list that can be processed by the $COMMxx caller.
Janus SDS, OPENSERV, or SRVSOCK For an 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 Model 204 AUDTERM or NOAUDTERM parameter controls whether the terminal output is sent to the audit trail (AUDTERM) or simply discarded (NOAUDTERM).
Janus Web For a WEB thread, the terminal output can either be the browser (if $Web_On is in effect) or the audit trail (if $Web_Off is in effect), although NOAUDTERM prevents non-compiler print lines from appearing on the audit trail, as with other Janus server threads.

As stated, $COMMxx can be used to process print output, since the Sdaemon 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 Sdaemon threads, and 3270 and IFDIAL/BATCH204 threads:

  1. The $List_Capture function directs print output to a $list.
  2. The $Sock_Capture function directs print output to a Janus Sockets connection.
  3. The Model 204 USE command directs print output to a USE stream.

For the above three facilities, "interactive" output is not sent to the $list, the socket, nor the USE stream, but instead is sent to the normal terminal output. The types of interactive output lines are:

TypeDescription
Messages Informational or error messages (for example, M204.nnnn or MSIR.nnnn) except when $List_Capture(id, 'MSGS') in effect.
Prompts Password prompts, $Read input, etc.
READ SCREEN SOUL full-screen display for input (note that Print Screen statements are subject to redirection)
WRITE IMAGE ON TERMINAL SOUL statement for sending lines directly to the normal terminal output

When an output line is redirected from the normal terminal output, it is directed based on the following hierarchy:

TypeConditions
$List_Capture Non-interactive print lines captured on $list, if one is active as specified to $List_Capture
$Sock_Capture Non-interactive print lines captured on one or more sockets, if any are specified as ON to $Sock_Capture, and if no $list is active as specified to $List_Capture ($List_Capture(-1) removes any active $list capture)
USE stream Non-interactive print lines directed to a USE stream, if it is active and there is no socket specified as ON to $Sock_Capture ($Sock_Capture(-1, 'OFF') removes all socket capturing) and if no $list is active as specified to $List_Capture
Normal terminal output Print lines are sent to the normal terminal output if none of the above print redirections are active

Below are some additional suggestions and considerations for the use of applications using print redirection in general and socket capturing in particular:

  • For output lines (non SCREEN output/input) that should go to the terminal, use WRITE IMAGE ON TERMINAL (on server applications, where the "terminal" output is the audit trail, you can use AUDIT instead).
  • The OUTCCC, OUTMRL, and LOBUFF limits are ignored for $Sock_Capture. A very long print line is captured as a single "logical" line (with a single trailing LINEND string, as specified on the JANUS DEFINE command or $Sock_Set for the socket).
  • Output lines sent by the "ellipsis" form of the Print statement (PRINT <items> ...) are captured without a trailing LINEND string. The LINEND string is sent at the end of the logical line (that is, OUTMRL, OUTCCC, and LOBUFF do not cause added LINEND strings to be sent). The LINEND string is not translated.
  • If the socket's LINEND parameter is NONE when a print line is captured, the line is simply sent without any string following it.
  • If the socket is set to CHAR, the print line is translated using the output translation table specified by the socket's XTAB parameter. If the socket is set to BINARY, the print line is not translated.
  • If you want a request to continue normal evaluation if a RESET condition is encountered on a socket, use $Sock_Set(socknum, 'ONRESET', 'CONTINUE'). When print capturing is attempted to an ONRESET CONTINUE socket, and the socket is RESET, Janus Sockets simply acts as if the print was captured and continues.
  • If CONTINUE is not in effect for a CAPTURE ON SOCKET that is RESET, a User Language print operation will jump to the ONRESET label if one is active, or else the request is cancelled (and any APSY ERROR procedure is evaluated). In this case, $Sock_ErrInfo returns -1 for CODE, and it returns the string Captured print for FUN.