$List Capture: Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Automatically generated page update)
m (misc formatting)
 
(10 intermediate revisions by 2 users not shown)
Line 2: Line 2:
<span class="pageSubtitle">Capture print data to $list</span>
<span class="pageSubtitle">Capture print data to $list</span>


<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $List_Capture function are the [[Text and Html statements]].</p>
<p class="warn"><b>Note:</b> Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the <var>$List_Capture</var> function are the [[Text and Html statements]]. </p>


This [[Calling Sirius Mods $functions|callable]] function captures print data onto a $list.  
This [[Calling Sirius Mods $functions|callable]] function captures print data onto a $list.  
Line 10: Line 10:
</p>
</p>


<table class="syntaxTable">
<table>
<tr><th>%old</th>
<tr><th>%old</th>
<td>The ID of the previous $list that captured print, or 0 if there is no such previous $list.</td></tr>
<td>The ID of the previous $list that captured print, or 0 if there is no such previous $list.</td></tr>
Line 18: Line 18:


<tr><th>options</th>
<tr><th>options</th>
<td>A blank delimited set of options. Currently, only the MSGS option, which captures <var class="product">Model 204</var> messages as well as print data, is valid. For more information about the MSGS option, see [[#Message capture and MSGCTL|Message capture and MSGCTL]].
<td>A blank-delimited set of options. Currently, only the <var>MSGS</var> option, which captures <var class="product">Model&nbsp;204</var> messages as well as print data, is valid. For more information about the <var>MSGS</var> option, see [[#Message capture and MSGCTL|Message capture and MSGCTL]].
<p>This is an optional argument. </p></td></tr>
<p>
This is an optional argument. </p></td></tr>
</table>
</table>


Line 46: Line 47:


<blockquote class="note">
<blockquote class="note">
<p>'''Note:''' <var>$List_Capture</var> ignores the usual length-of-print-line limits of the <var class="product">Model 204</var> <var>[[OUTCCC parameter|OUTCC]]</var> and <var>[[OUTMRL parameter|OUTMRL]]</var> parameters, but it still respects <var>[[LOBUFF parameter|LOBUFF]]</var>: each print output line is truncated at <var>LOBUFF</var> bytes. The <var>LOBUFF</var> limit, which is not resettable during the Online run, is the only limit on captured $list item size. </p>
<p>'''Note:''' <var>$List_Capture</var> ignores the usual length-of-print-line limits of the <var class="product">Model&nbsp;204</var> <var>[[OUTCCC parameter|OUTCC]]</var> and <var>[[OUTMRL parameter|OUTMRL]]</var> parameters, but it still respects <var>[[LOBUFF parameter|LOBUFF]]</var>: each print output line is truncated at <var>LOBUFF</var> bytes. The <var>LOBUFF</var> limit, which is not resettable during the Online run, is the only limit on captured $list item size. </p>
<p>
<p>
For example, a sequence of statements like these below places two items in the $list, each of which is subject to the above formatting rules:</p>
For example, a sequence of statements like these below places two items in the $list, each of which is subject to the above formatting rules:</p>
Line 65: Line 66:


===Print capturing hierarchy and other considerations===
===Print capturing hierarchy and other considerations===
The <var class="product">User Language</var> <var>Print</var> statement and the Sirius <var>Html</var> statement are a few of many "print" operations that can produce output lines for an application. These operations "normally" send their output to the "terminal" 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 <var class="product">SOUL</var> <var>Print</var> statement and the <var>Html</var> statement are a few of many "print" operations that can produce output lines for an application. These operations "normally" send their output to the "terminal" for the thread running the application.  
 
<p>
The terminal output of an SDAEMON thread (usually IODEV=15) depends on how the SDAEMON was started:
'''Terminal output''' refers to the print destination defined by the <var>IODEV</var> for the thread. For example, the terminal output of an <var>IODEV</var> 7 (VTAM) terminal user is the user's 3270-style terminal; the terminal output of an <var>IODEV</var> 29 (IFDIAL, or BATCH2) user is the MVS batch program that retrieves the output lines. </p>
<p>
The terminal output of an [[Sdaemons|Sdaemon]] thread (usually <var>IODEV</var> 15) depends on how the Sdaemon was started: </p>


<table class="thJustBold">
<table class="thJustBold">
<tr><th>$COMMxx</th>
<tr><th>$COMMxx</th>
<td>If the thread was started by a Sirius <var>$COMMxx</var> function, the output can be saved in a Sirius $list that can be processed by the <var>$COMMxx</var> caller.</td></tr>
<td>If the thread was started by a <var>$COMMxx</var> function, the output can be saved in a $list that can be processed by the <var>$COMMxx</var> caller.</td></tr>
 
<tr><th nowrap>Janus SDS, OPENSERV, or SRVSOCK</th>
<tr><th nowrap>Janus SDS, OPENSERV, or SRVSOCK</th>
<td>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 AUDTERM/NOAUDTERM parameter controls whether the terminal output is sent to the audit trail (AUDTERM) or simply discarded (NOAUDTERM).</td></tr>
<td>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 <var>AUDTERM</var>/<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 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.
</td></tr></table>


<tr><th>Janus Web</th>
<td>For a Web 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, <var>$COMMxx</var> 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:
As stated, <var>$COMMxx</var> can be used to process print output, since the Sdaemon doing its work can place print output in a $list. There are also facilities for processing print output on any kind of thread, including other Sdaemon threads, and 3270 and IFDIAL/BATCH204 threads:


<ul>
<ul>
<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 Sirius $list.  
<li>The <var>$SockCapture</var> setting directs print output to a <var class="product">[[Janus Sockets]]</var> connection.  
<li>The <var>$SockCapture</var> setting directs print output to a <var class="product">[[Janus Sockets]]</var> connection.  
<li>The <var>[[USE command|USE]]</var> command directs print output to a USE stream.
<li>The <var>[[USE command: Directing output|USE]]</var> command directs print output to a <var>USE</var> stream.
</ul>
</ul>


Line 90: Line 95:


<ul>
<ul>
<li>Messages &#x2014; Informational or error messages (for example, <code>M204.<i>nnnn</i></code> or <code>MSIR.<i>nnnn</i></code>), except when <code>$List_Capture(id, 'MSGS')</code> is in effect
<li>Messages &mdash; Informational or error messages (for example, <code>M204.<i>nnnn</i></code> or <code>MSIR.<i>nnnn</i></code>), except when <code>$List_Capture(id, 'MSGS')</code> is in effect. </li>


<li>Prompts &#x2014; Password prompts, <var>$READ</var> input, etc.
<li>Prompts &mdash; Password prompts, <var>$READ</var> input, etc. </li>


<li>READ SCREEN &#x2014; <var class="product">User Language</var> full-screen display for input (note: PRINT SCREEN statements '''are''' subject to redirection)
<li>READ SCREEN &mdash; <var class="product">SOUL</var> full-screen display for input.
<p class="note"><b>Note:</b> <var>Print Screen</var> statements '''are''' subject to redirection. </p></li>


<li>WRITE IMAGE ON TERMINAL
<li>WRITE IMAGE ON TERMINAL</li>


<li><var class="product">User Language</var> statement for sending lines directly to the normal terminal output.
<li><var class="product">SOUL</var> statement for sending lines directly to the normal terminal output. </li>
</ul>
</ul>


Line 107: Line 113:
<li><var>$Sock_Capture</var> &#x2014; Non-interactive print lines captured on one or more sockets, if any are specified as ON to <var>$Sock_Capture</var>, and if no $list is active as specified to <var>$List_Capture</var>  
<li><var>$Sock_Capture</var> &#x2014; Non-interactive print lines captured on one or more sockets, if any are specified as ON to <var>$Sock_Capture</var>, and if no $list is active as specified to <var>$List_Capture</var>  


<li>USE stream &#x2014; Non-interactive print lines directed to a USE stream, if it is active and if a) there is no socket specified as ON to $SOCK_CAPTURE, and b) no $list is active as specified to <var>$List_Capture</var>  
<li><var>USE</var> stream &#x2014; Non-interactive print lines directed to a USE stream, if it is active and if a) there is no socket specified as ON to <var>$SockCapture</var>, and b) no $list is active as specified to <var>$List_Capture</var>  


<li>Print lines are sent to the normal terminal output if none of the above print redirections is active.
<li>Print lines are sent to the normal terminal output if none of the above print redirections is active.
</ul>
</ul>


For output lines (non SCREEN output/input) that should be forced to go to the terminal, use WRITE IMAGE ON TERMINAL (on server applications, where the "terminal" output is the audit trail, use AUDIT instead).
For output lines (non SCREEN output/input) that should be forced to go to the terminal, use <code>WRITE IMAGE ON TERMINAL</code> (on server applications, where the "terminal" output is the audit trail, use <code>AUDIT</code> instead).


===Message capture and MSGCTL===
===Message capture and MSGCTL===
If the MSGS option is specified, <var>$List_Capture</var> captures the messages that go to the "terminal." This is true, however, as long as the messages are not being suppressed.  
If the <var>MSGS</var> option is specified, <var>$List_Capture</var> captures the messages that go to the "terminal." This is true, however, as long as the messages are not being suppressed.  


<var>$List_Capture</var> does not capture terminal messages that are suppressed by the MSGCTL system command or the MSGCTL user parameter. The latter is especially important because many APSY subsystems suppress error and/or informational messages by setting the MSGCTL X'04' and/or X'02' bits. This is done automatically by <var class="product">Model 204</var> when the subsystem is defined to suppress error or informational messages.  
<var>$List_Capture</var> does not capture terminal messages that are suppressed by the <var>MSGCTL</var> system command or the <var>MSGCTL</var> user parameter. The latter is especially important because many APSY subsystems suppress error and/or informational messages by setting the <var>MSGCTL</var> X'04' and/or X'02' bits. This is done automatically by <var class="product">Model&nbsp;204</var> when the subsystem is defined to suppress error or informational messages.  


If the X'04' and/or X'02' MSGCTL bits are set, they must be cleared for <var>$List_Capture</var> to actually capture error or informational messages. You can clear these bits with the <var>[[$Resetn]]</var> function in a <var class="product">User Language</var> application.
If the X'04' and/or X'02' <var>MSGCTL</var> bits are set, they must be cleared for <var>$List_Capture</var> to actually capture error or informational messages. You can clear these bits with the <var>[[$Resetn]]</var> function in a <var class="product">SOUL</var> application.


==Products authorizing {{PAGENAMEE}}==  
==Products authorizing {{PAGENAMEE}}==  
<ul class="smallAndTightList">
<ul class="smallAndTightList">
<li>[[Sirius functions]]</li>
<li>[[Sirius Functions]]</li>
<li>[[Fast/Unload User Language Interface]]</li>
<li>[[Fast/Unload User Language Interface]]</li>
<li>[http://m204wiki.rocketsoftware.com/images/4/4a/JoclrNew.pdf Janus Open Client]</li>
<li>[[Media:JoclrNew.pdf|Janus Open Client]]</li>
<li>[http://m204wiki.rocketsoftware.com/images/1/17/JosrvrNew.pdf Janus Open Server]</li>
<li>[[Media:JosrvrNew.pdf|Janus Open Server]]</li>
<li>[[Janus Sockets]]</li>
<li>[[Janus Sockets]]</li>
<li>[[Janus Web Server]]</li>
<li>[[Janus Web Server]]</li>
<li>[[Japanese functions]]</li>
<li>Japanese functions</li>
<li>[http://m204wiki.rocketsoftware.com/images/4/4b/SirfieldNew.pdf Sir2000 Field Migration Facility]</li>
<li>[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility]]</li>
</ul>
</ul>
   
   
[[Category:$Functions|$List_Capture]]
[[Category:$Functions|$List_Capture]]

Latest revision as of 22:59, 5 June 2018

Capture print data to $list

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $List_Capture function are the Text and Html statements.

This callable function captures print data onto a $list.

Syntax

[%old =] $List_Capture([list_id], [options])

%old The ID of the previous $list that captured print, or 0 if there is no such previous $list.
list_id The $list identifier; 0 sets the print capture function to off. This argument is optional, and it defaults to 0.
options A blank-delimited set of options. Currently, only the MSGS option, which captures Model 204 messages as well as print data, is valid. For more information about the MSGS option, see Message capture and MSGCTL.

This is an optional argument.

$List_Capture error conditions

$List identifier invalid: Request is cancelled Invalid option: Request is cancelled

Example

To sort an arbitrary set of print lines:

%L = $ListNew %R = $List_Capture(%L) PRINT 'HELLO' PRINT 'GOODBYE' %R = $List_Capture %J = $ListSrt(%L, '1,10,A') FOR %R FROM 1 TO $ListCnt(%J) PRINT $ListInf(%J, %R) END FOR

Usage notes

  • When print data is captured to a $list, each print line is added as an item to the $list.

    Note: $List_Capture ignores the usual length-of-print-line limits of the Model 204 OUTCC and OUTMRL parameters, but it still respects LOBUFF: each print output line is truncated at LOBUFF bytes. The LOBUFF limit, which is not resettable during the Online run, is the only limit on captured $list item size.

    For example, a sequence of statements like these below places two items in the $list, each of which is subject to the above formatting rules:

    %x = $List_Capture(%ll) Print %s Print %t

    However, in the following example, the Print statements concatenate, in effect, and one item only is placed in the $list, subject to the above formatting rules:

    %x = $slist_capture(%ll) Print %s ... Print %t

Print capturing hierarchy and other considerations

The SOUL Print statement and the Html statement are a few of many "print" operations that can produce output lines for an application. These operations "normally" send their output to the "terminal" 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 $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 AUDTERM/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 $list. There are also facilities for processing print output on any kind of thread, including other Sdaemon threads, and 3270 and IFDIAL/BATCH204 threads:

  • The $List_Capture function directs print output to a Sirius $list.
  • The $SockCapture setting directs print output to a Janus Sockets connection.
  • The 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:

  • Messages — Informational or error messages (for example, M204.nnnn or MSIR.nnnn), except when $List_Capture(id, 'MSGS') is in effect.
  • Prompts — Password prompts, $READ input, etc.
  • READ SCREEN — SOUL full-screen display for input.

    Note: 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 according to the following hierarchy:

  • $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
  • USE stream — Non-interactive print lines directed to a USE stream, if it is active and if a) there is no socket specified as ON to $SockCapture, and b) no $list is active as specified to $List_Capture
  • Print lines are sent to the normal terminal output if none of the above print redirections is active.

For output lines (non SCREEN output/input) that should be forced to go to the terminal, use WRITE IMAGE ON TERMINAL (on server applications, where the "terminal" output is the audit trail, use AUDIT instead).

Message capture and MSGCTL

If the MSGS option is specified, $List_Capture captures the messages that go to the "terminal." This is true, however, as long as the messages are not being suppressed.

$List_Capture does not capture terminal messages that are suppressed by the MSGCTL system command or the MSGCTL user parameter. The latter is especially important because many APSY subsystems suppress error and/or informational messages by setting the MSGCTL X'04' and/or X'02' bits. This is done automatically by Model 204 when the subsystem is defined to suppress error or informational messages.

If the X'04' and/or X'02' MSGCTL bits are set, they must be cleared for $List_Capture to actually capture error or informational messages. You can clear these bits with the $Resetn function in a SOUL application.

Products authorizing $List_Capture