$List Capture: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (misc formatting)
 
(40 intermediate revisions by 3 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="warning">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 function captures print data onto a $list.  
This [[Calling Sirius Mods $functions|callable]] function captures print data onto a $list.  


<var>$List_Capture</var> accepts the two arguments described below. It returns the identifier of the previous $list that captured print, or it returns 0 if there is no such previous $list. It is a callable $function (see [[Calling Sirius Mods $functions]]).
==Syntax==
<p class="syntax">[<span class="term">%old</span> =] <span class="literal">$List_Capture</span>([<span class="term">list_id</span>], [<span class="term">options</span>])
</p>


<ul>
<table>
<li>The first argument is the $list identifier; 0 sets the print capture function to off. This argument is optional, and it defaults to 0.
<tr><th>%old</th>
<li>The second argument, which is optional, is 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>The ID of the previous $list that captured print, or 0 if there is no such previous $list.</td></tr>
</ul>


==Syntax==
<tr><th>list_id</th>
<p class="syntax"><section begin="syntax" /> [%OLD =] $List_Capture(list_id, options)
<td>The $list identifier; 0 sets the print capture function to off. This argument is optional, and it defaults to 0. </td></tr>
<section end="syntax" /></p>


<p class="caption">%OLD is the ID of the previous $list-capturing print.</p>
<tr><th>options</th>
<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>
</table>


For example, you can sort an arbitrary set of print lines:
===$List_Capture error conditions===
<p class="code">$List identifier invalid: Request is cancelled
Invalid option: Request is cancelled
</p>


<p class="code"> %L = $ListNew
==Example==
%R = $List_Capture(%L)
To sort an arbitrary set of print lines:
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
</p>


<p class="code">  
<p class="code">%L = $ListNew
- $List identifier invalid: Request is cancelled
%R = $List_Capture(%L)
- Invalid option: Request is cancelled
PRINT 'HELLO'
</p>
PRINT 'GOODBYE'
<p class="caption">$List_Capture Error Conditions
%R = $List_Capture
%J = $ListSrt(%L, '1,10,A')
FOR %R FROM 1 TO $ListCnt(%J)
  PRINT $ListInf(%J, %R)
END FOR
</p>
</p>


Line 43: Line 46:
<li>When print data is captured to a $list, each print line is added as an item to the $list.
<li>When print data is captured to a $list, each print line is added as an item to the $list.


<li>'''Note:''' In Versions of <var class="product">[[Sirius Mods]]</var> prior to 6.4, the list capture of these lines respects the <var class="product">Model 204</var> OUTCCC, OUTMRL, and LOBUFF parameter formatting. That is, a print line longer than OUTCCC wraps, and it is captured as an additional $list item for each time that it wraps. A print line longer than OUTMRL or LOBUFF is truncated at OUTMRL or LOBUFF bytes, respectively.
<blockquote class="note">
<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>
As of Version 6.4 of <var class="product">Sirius Mods</var>, the OUTCCC and OUTMRL limits are ignored for $LIST_CAPTURE, but LOBUFF is still respected. Each print output line is truncated at LOBUFF bytes. The LOBUFF limit, which is not resettable during the Online run, does not affect the total length of the $list. Under <var class="product">Sirius Mods</var> Version 6.5 or earlier captured items are truncated at 6124 bytes even if LOBUFF is greater than 6124. Under <var class="product">Sirius Mods</var> Version 6.6 and later, LOBUFF 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>
<p class="code">%X = $List_Capture(%LL)
<p class="code">%x = $List_Capture(%ll)
   
   
PRINT %S
Print %s
PRINT %T
Print %t
</p>
</p>
<p>
<p>
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:</p>
However, in the following example, the <code>Print</code> statements concatenate, in effect, and one item only is placed in the $list, subject to the above formatting rules:</p>
<p class="code">%X = $SLIST_CAPTURE(%LL)
<p class="code">%x = $slist_capture(%ll)
   
   
PRINT %S ...
Print %s ...
PRINT %T
Print %t
</p>
</p>
</blockquote>
</ul>
</ul>
<ul class="smallAndTightList">
<li>[[Sirius functions]]</li>
<li>[[Fast/Unload User Language Interface]]</li>
<li>[[Janus Open Client]]</li>
<li>[[Janus Open Server]]</li>
<li>[[Janus Sockets]]</li>
<li>[[Janus Web Server]]</li>
<li>[[Japanese functions]]</li>
<li>[[Sir2000 Field Migration Facility]]</li>
</ul>
<p class="caption">Products authorizing $List_Capture
</p>


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


The terminal output of an SDAEMON thread (usually IODEV=15) depends on how the SDAEMON was started:
<table class="thJustBold">
<tr><th>$COMMxx</th>
<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>


<table class="syntaxTable">
<tr><th>$COMMxx</th>
<td>If the thread was started by a Sirius $COMMxx function, the output can be saved in a Sirius $list that can be processed by the $COMMxx 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, $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:
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 $List_Capture function directs print output to a Sirius $list.  
<li>The <var>$List_Capture</var> function directs print output to a Sirius $list.  
<li>The $SOCK_CAPTURE setting directs print output to a ''[[Janus Sockets]]'' connection. See the ''Janus Sockets Reference Manual''.  
<li>The <var>$SockCapture</var> setting directs print output to a <var class="product">[[Janus Sockets]]</var> connection.  
<li>The USE command, as documented in the ''"Model 204 Command Reference Manual"'', 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 103: Line 95:


<ul>
<ul>
<li>Messages -- Informational or error messages (for example, M204.nnnn or MSIR.nnnn), except when $List_Capture(id, 'MSGS') 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 -- Password prompts, $READ input, etc.
 
<li>READ SCREEN -- <var class="product">User Language</var> full-screen display for input (note: PRINT SCREEN statements '''are''' subject to redirection)
<li>Prompts &mdash; Password prompts, <var>$READ</var> input, etc. </li>
<li>WRITE IMAGE ON TERMINAL
 
<li><var class="product">User Language</var> statement for sending lines directly to the normal terminal output.
<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>
 
<li><var class="product">SOUL</var> statement for sending lines directly to the normal terminal output. </li>
</ul>
</ul>


When an output line is redirected from the normal terminal output, it is directed according to the following hierarchy:  
When an output line is redirected from the normal terminal output, it is directed according to the following hierarchy:  
<ul>
<ul>
<li>$List_Capture -- Non-interactive print lines captured on $list, if one is active as specified to <var>$List_Capture</var>  
<li><var>$List_Capture</var> &#x2014; Non-interactive print lines captured on $list, if one is active as specified to <var>$List_Capture</var>  
<li>$SOCK_CAPTURE -- 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 -- 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 $List_Capture  
<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>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, LIST_CAPTURE captures the messages that go to the "terminal.&amp;CQ. 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 $List_Capture 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}}==
<ul class="smallAndTightList">
<li>[[Sirius Functions]]</li>
<li>[[Fast/Unload User Language Interface]]</li>
<li>[[Media:JoclrNew.pdf|Janus Open Client]]</li>
<li>[[Media:JosrvrNew.pdf|Janus Open Server]]</li>
<li>[[Janus Sockets]]</li>
<li>[[Janus Web Server]]</li>
<li>Japanese functions</li>
<li>[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility]]</li>
</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