$List Capture

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

• Sirius Functions
• Fast/Unload User Language Interface
• Janus Open Client
• Janus Open Server
• Janus Sockets
• Janus Web Server
• Japanese functions
• Sir2000 Field Migration Facility