$List_Capture
Capture print data to $list
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.
This callable function captures print data onto a $list.
Syntax
<section begin="syntax" />[%old =] $List_Capture(list_id, [options]) <section end="syntax" />
| %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. |
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
$List_Capture error conditions
$List identifier invalid: Request is cancelled Invalid option: Request is cancelled
Usage notes
- When print data is captured to a $list, each print line is added as an item to the $list.
- Note: In Versions of Sirius Mods prior to 6.4, the list capture of these lines respects the Model 204 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.
As of Version 6.4 of Sirius Mods, 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 Sirius Mods Version 6.5 or earlier captured items are truncated at 6124 bytes even if LOBUFF is greater than 6124. Under Sirius Mods Version 6.6 and later, LOBUFF 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 User Language Print statement and the Sirius 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 Sirius $COMMxx function, the output can be saved in a Sirius $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 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:
- The $List_Capture function directs print output to a Sirius $list.
- The $SOCK_CAPTURE setting directs print output to a Janus Sockets connection. See the Janus Sockets Reference Manual.
- The USE command, as documented in the "Model 204 Command Reference Manual", 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 -- User Language full-screen display for input (note: PRINT SCREEN statements are subject to redirection)
- WRITE IMAGE ON TERMINAL
- User Language 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 $SOCK_CAPTURE, 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.&CQ. 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 User Language application.