$Sock_Capture

Change print capture setting

Note: Most Sirius $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:

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

Type	Description
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	`User Language` full-screen display for input (note that `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 based on the following hierarchy:

Type	Conditions
$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).
In versions of Sirius Mods prior to 6.4, the capturing of print 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 line 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, 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.