OUTTRAP


>>-OUTTRAP(-+----------------------------------------------------------+-)-><
            +-off------------------------------------------------------+     
            '-varname-+----------------------------------------------+-'     
                      '-,-+-----+-+--------------------------------+-'       
                          '-max-' '-,-+--------+-+---------------+-'         
                                      '-concat-' '-,-+---------+-'           
                                                     '-skipamt-'

OUTTRAP returns the name of the variable in which trapped output is stored, or if trapping is not in effect, OUTTRAP returns the word off.

You can use the following arguments to trap lines of command output into compound variables or a series of numbered variables, or to turn trapping off that was previously started.

off

specify the word OFF to turn trapping off.

varname

the stem of the compound variables or the variable prefix assigned to receive the command output. Compound variables contain a period and allow for indexing, but lists of variables with the same prefix cannot be accessed by an index in a loop.

Note: Do not use "OFF" as a variable name.

max

the maximum number of lines to trap. You can specify a number, an asterisk in quotation marks (‘*’), or a blank. If you specify ‘*’ or a blank, all the output is trapped. The default is 999,999,999. If the maximum number of lines are trapped, subsequent lines are not stored in variables.

concat

indicates how output should be trapped. For concat, specify one of the following:

CONCAT
indicates that output from commands be trapped in consecutive order until the maximum number of lines is reached. For example, if the first command has three lines of output, they are stored in variables ending in 1, 2, and 3. If the second command has two lines of output, they are stored in variables ending in 4 and 5. The default order for trapping is CONCAT.
NOCONCAT
indicates that output from each command be trapped starting at the variable ending in 1. For example, if the first command has three lines of output, they are stored in variables ending in 1, 2, and 3. If another command has two lines of output, they replace the first command's output in variables 1 and 2.

skipamt

specifies the number of lines to be skipped before trapping begins. If skipamt is not specified, the default is 0. The highest skip amount allowed is 999,999,999.

Lines of output are stored in successive variable names (as specified by varname) concatenated with integers starting with 1. All unused variables display their own names. The number of lines that were trapped is stored in the variable name followed by 0. For example, if you specify cmdout. as the varname, the number of lines stored is in:

cmdout.0

If you specify cmdout as the varname, the number of lines stored is in:

cmdout0

An exec can use these variables to display or process TSO/E command output. Error messages from TSO/E commands are trapped, but other types of error messages are sent to the terminal. Trapping, once begun, continues from one exec to other invoked execs or CLISTs. Trapping ends when the original exec ends or when trapping is turned off.

You can use the OUTTRAP function only in REXX execs that run using ADDRESS TSO.

Environment Customization Considerations: If you use IRXINIT to initialize language processor environments, note that you can use OUTTRAP only in environments that are integrated into TSO/E (see Types of environments - integrated and not integrated into TSO/E).

OUTTRAP traps output from commands, including those written in REXX. A command written in REXX cannot turn output trapping off on behalf of its invoker. Output trapping should be turned on and off at the same exec level. Therefore, a command written in REXX should only turn output trapping off if that command turned it on. In the following examples, the first illustrates correct usage of OUTTRAP; the second incorrect usage. Note that the placement of the y = OUTTRAP('OFF') statement must be within the REXX1 exec, not the REXX2 command.

Correct usage of OUTTRAP

x = OUTTRAP('VAR.')
"%REXX2"
y = OUTTRAP('OFF')
EXIT

/* REXX2 command */
SAY "This is output from the REXX2 command " /* This will be trapped */
RETURN

Incorrect usage of OUTTRAP

/* REXX1 */
x = OUTTRAP('VAR.')
"%REXX2"
EXIT

/* REXX2 command */
SAY "This is output from the REXX2 command " /* This will be trapped */
y = OUTTRAP('OFF')
RETURN

To trap the output of TSO/E commands under ISPF, you must invoke an exec with command output after ISPF or one of its services has been invoked.

The output of authorized commands listed under the AUTHCMD parameter in the active IKJTSOxx parmlib member cannot be trapped by a REXX exec invoked under any application that builds its own ECT. For example, a REXX exec must be prefixed by the TSO subcommand of IPCS to trap the output of authorized commands when invoked from IPCS under ISPF.

Regardless of the user's region size, the variables used to trap output from authorized commands and programs are limited to storage below the 16MB line, unless the PROFILE setting of VARSTORAGE(HIGH) is in use. If VARSTORAGE(HIGH) is specified in the user's PROFILE setting, using storage above the 16MB line is possible, and REXX can trap more lines of output from an authorized command or program.

OUTTRAP may not trap all of the output from a TSO/E command. The output that the OUTTRAP function traps depends on the type of output that the command produces. For example, the TSO/E command OUTPUT PRINT(*) directs the output from a job to your terminal. The OUTTRAP external function traps messages from the OUTPUT PRINT(*) command, but does not trap the job output itself that is directed to the terminal.

In general, the OUTTRAP function traps all output from a TSO/E command. For example, OUTTRAP traps broadcast messages from LISTBC, the list of allocated data sets from LISTALC, catalog entries from LISTCAT, and so on.

If you plan to write your own command processors for use in REXX execs, and you plan to use the OUTTRAP external function to trap command output, note the OUTTRAP function does not trap command output that is sent to the terminal by:

TPUT
WTO macro
messages issued by TSO/E REXX (that is, messages beginning with IRX)
Note: The TRAPMSG can be used to override this setting to allow IRX messages issued by TSO/E REXX or by a REXX host command like EXECIO to be trapped.
messages issued by TRACE output.
Note: Messages issued by TRACE output can be trapped if the exec being traced has been invoked by a higher level exec that uses OUTTRAP to enable output trapping and then invokes the exec to be traced.

However, OUTTRAP does trap output from the PUTLINE macro with DATA or INFOR keywords. Therefore, if you write any command processors, you may want to use the PUTLINE macro rather than the TPUT or WTO macros. z/OS TSO/E Programming Guide describes how to write a TSO/E command processor. For information about the PUTLINE macro, see z/OS TSO/E Programming Services.

Additional Variables That OUTTRAP Sets

In addition to the variables that store the lines of output, OUTTRAP stores information in the following variables:

varname0: contains the largest index into which output was trapped. The number in this variable cannot be larger than varnameMAX or varnameTRAPPED.
varnameMAX: contains the maximum number of output lines that can be trapped. That is, the total number of lines generated by commands while OUTPUT trapping is in effect. See example 1.
varnameTRAPPED: contains the total number of lines of command output. The number in this variable can be larger than varname0 or varnameMAX.
varnameCON: contains the status of the concat argument, which is either CONCAT or NOCONCAT.
varnameSKIPPED: contains the number of output lines that have been skipped so far. This variable cannot be larger than varnameSKIPAMT.
varnameSKIPAMT: contains the total number of output lines that must be skipped before the first output line is trapped in varname1.
If a non-zero skip amount is specified, the number of lines that are skipped is still counted as part of the varnameTRAPPED value. Any lines of output ignored after the vanameMAX limit has been reached are still be counted as part of the varnameTRAPPED value.

Examples:

The following are some examples of using OUTTRAP.

This example shows the resulting values in variables after the following OUTTRAP function is processed.

x = OUTTRAP("ABC",4,"CONCAT")

 "Command1" /* sample command producing 3 lines of output */

Command 1 has three lines of output. After command 1 runs, the following variables are set.

ABC0            -->  3
ABC1            -->  command 1 output line 1
ABC2            -->  command 1 output line 2
ABC3            -->  command 1 output line 3
ABC4            -->  ABC4
ABCMAX          -->  4
ABCTRAPPED      -->  3
ABCCONCAT      --> CONCAT
ABCSKIPPED      --> 0
ABCSKIPAMT      --> 0

"Command2" /* sample command producing 2 lines of output */

Command 2 has two lines of output. After command 2 runs, the following variables are set. Note that the second line of output from command 2 is not trapped because the MAX (4) is reached when the first line of output from command 2 is produced.

ABC0            -->  4
ABC1            -->  command 1 output line 1
ABC2            -->  command 1 output line 2
ABC3            -->  command 1 output line 3
ABC4            -->  command 2 output line 1
ABCMAX          -->  4
ABCTRAPPED      -->  5
ABCCONCAT      --> CONCAT
ABCSKIPPED      --> 0
ABCSKIPAMT      --> 0

This example shows the resulting values in variables after the following OUTTRAP function is processed.

x = OUTTRAP("XYZ.",4,"NOCONCAT")

"Command1" /* sample command producing 3 lines of output */

Command 1 has three lines of output. After command1 runs, the following variables are set.

XYZ.0           -->  3
XYZ.1           -->  command 1 output line 1
XYZ.2           -->  command 1 output line 2
XYZ.3           -->  command 1 output line 3
XYZ.4           -->  XYZ.4
XYZ.MAX         -->  4
XYZ.TRAPPED     -->  3
XYZ.CONCAT     --> NOCONCAT
XYZ.SKIPPED     --> 0
XYZ.SKIPAMT     --> 0

"Command2" /* sample command producing 2 lines of output */

Command 2 has two lines of output. Because NOCONCAT was specified, output from Command 2 may replace output values trapped from Command 1. However, because only 2 lines were trapped by command 2, only 2 of the three lines trapped by Command 1 are replaced. XYZ.3 continues to contain the residual output from Command 1.

XYZ.0           -->  2
XYZ.1           -->  command 2 output line 1
XYZ.2           -->  command 2 output line 2
XYZ.3           -->  command 1 output line 3
XYZ.4           -->  XYZ.4
XYZ.MAX         -->  4
XYZ.TRAPPED     -->  2
XYZ.CONCAT     --> NOCONCAT
XYZ.SKIPPED     --> 0
XYZ.SKIPAMT     --> 0

To determine if trapping is in effect, enter the following:

x = OUTTRAP()
SAY x           /* If the exec is trapping output, displays the  */
                /* variable name; if it is not trapping output, */
                /* displays OFF */

To trap output from commands in consecutive order into the stem

output.

use one of the following:

x = OUTTRAP("output.",'*',"CONCAT")

x = OUTTRAP("output.")

x = OUTTRAP("output.",,"CONCAT")

To trap 6 lines of output into the variable prefix line and not concatenate the output, enter the following:
```
x = OUTTRAP(line,6,"NOCONCAT")
```
To suppress all command output, enter the following:
```
x = OUTTRAP("output",0)
```
Guideline: This form of OUTTRAP provides the best performance for suppressing command output.
Allocate a new data set like an existing one and if the allocation is successful, delete the existing data set. If the allocation is not successful, display the trapped output from the ALLOCATE command.
```
x = OUTTRAP("var.")
"ALLOC DA(new.data) LIKE(old.data) NEW"
IF RC = 0 THEN
  "DELETE old.data"
ELSE
  DO i = 1 TO var.0
     SAY var.i
  END
```
If the ALLOCATE command is not successful, error messages are trapped in the following compound variables.
- VAR.1 = error message
- VAR.2 = error message
- VAR.3 = error message

This example shows the resulting values in variables after the following OUTTRAP function is performed, using the SKIP argument of OUTTRAP to skip over lines of output before trapping begins.

x = OUTTRAP("XYZ.",10,"CONCAT",50)

"CMD1"             /* CMD1 produces 40 lines of output */

CMD1 has 40 lines of output. Because 40 is less than 50, no lines of CMD1 are trapped. After CMD1, OUTTRAP variables have the following values:

XYZ.0                   --> 0           No lines trapped yet 
XYZ.1                   --> XYZ.1
XYZ.2                   --> XYZ.2 
XYZ.3                   --> XYZ.3 
XYZ.4                   --> XYZ.4 
XYZ.5                   --> XYZ.5 
XYZ.6                   --> XYZ.6
XYZ.7                   --> XYZ.7 
XYZ.8                   --> XYZ.8 
XYZ.9                   --> XYZ.9 
XYZ.10                 --> XYZ.10
XYZ.MAX             --> 10
XYZ.TRAPPED    --> 40          40 lines of output handled so far
XYZ.CON             --> CONCAT
XYZ.SKIPPED     --> 40          Number of lines skipped so far
XYZ.SKIPAMT     --> 50          Total number to skip before trapping

"CMD2"             /* CMD2 produces 15 more lines of output */

CMD2 has 15 lines of output. 10 additional lines will be skipped, and trapping will begin with the 11th line (51st line overall).

XYZ.0                   --> 5           5 lines trapped
XYZ.1                   --> cmd2 output line 11 (output line 51 overall)
XYZ.2                   --> cmd2 output line 12 (output line 52 overall)
XYZ.3                   --> cmd2 output line 13 (output line 53 overall)
XYZ.4                   --> cmd2 output line 14 (output line 54 overall)
XYZ.5                   --> cmd2 output line 15 (output line 55 overall)
XYZ.6                   --> XYZ.6
XYZ.7                   --> XYZ.7
XYZ.8                   --> XYZ.8
XYZ.9                   --> XYZ.9
XYZ.MAX             --> 10
XYZ.10                 --> XYZ.10
XYZ.TRAPPED    --> 55          55 lines of output handled so far
XYZ.CON             --> CONCAT
XYZ.SKIPPED     --> 50          Number of lines skipped so far
XYZ.SKIPAMT     --> 50          Total number to skip before trapping

When skipping is in effect, the 1st line trapped into variable XYZ.1 is the (XYZ.SKIPAMT +1) line of output.

"CMD3"             /* CMD3 produces 10 more lines of output */

CMD3 has 10 lines of output. 5 additional lines will be trapped until MAX has been reached, and the remaining lines are discarded.

XYZ.0                   --> 10          10 lines trapped
XYZ.1                   --> cmd2 output line 11 (output line 51 overall)
XYZ.2                   --> cmd2 output line 12 (output line 52 overall)
XYZ.3                   --> cmd2 output line 13 (output line 53 overall)
XYZ.4                   --> cmd2 output line 14 (output line 54 overall)
XYZ.5                   --> cmd2 output line 15 (output line 55 overall)
XYZ.6                   --> cmd3 output line 1 (output line 56 overall)
XYZ.7                   --> cmd3 output line 2 (output line 57 overall)
XYZ.8                   --> cmd3 output line 3 (output line 58 overall)
XYZ.9                   --> cmd3 output line 4 (output line 59 overall)
XYZ.10                 --> cmd3 output line 5 (output line 60 overall)
XYZ.MAX             --> 10
XYZ.TRAPPED    --> 65          65 lines of output handled so far
XYZ.CON             --> CONCAT
XYZ.SKIPPED     --> 50          Number of lines skipped so far
XYZ.SKIPAMT     --> 50          Total number to skip before trapping

The first line of output trapped is the XYZ.SKIPAMT+1 -th output line. The last line trapped is the XYZ.SKIPAMT+XYZ.MAX -th output line. Any output lines after this are not trapped.
The first line trapped is always placed in the XYZ.1 variable.
The highest indexed variable into which output can be trapped is XYZ.n (where n=XYZ.MAX).
PUTLINE output lines that are skipped behave as if they were trapped and discarded. The output is not written to the screen, and the skipped lines are not actually trapped. However, each skipped line does count in the total number of output lines processed (varnameTRAPPED).

A user is about to use a REXX exec to invoke an authorized command "MYACMD". The exec uses OUTTRAP to trap and process the output. Although the command can produce 500,000 or more lines of output, the user is only interested in the last 70,000 lines and wants to capture these lines and write them to a data set to be processed later.

The user issues the PROFILE command without operands to see the current settings, and to ensures that the VARSTORAGE setting is HIGH.

PROFILE
IKJ56688I CHAR(0) LINE(0) PROMPT INTERCOM NOPAUSE MSGID NOMODE WTPMSG
NORECOVER PREFIX(TUSER01) PlANGUAGE(ENU) SLANGUAGE(ENU) VARSTORAGE(HIGH)
IKJ56689I DEFAULT LINE/CHARACTER DELETE CHARACTERS IN EFFECT FOR THIS
TERMINAL

If the VARSTORAGE setting is LOW he can change it to HIGH

PROFILE VARSTORAGE(HIGH)

The user then invokes the following exec:

/* REXX */
"ALLOC FI(OUTDD) DA(...my output data set...) SHR REUSE"
/* ... other processing ... */

/***********************************************************/
/* First determine how much output the command produces.   */
/* Specify a MAXAMT of 0 (2nd operand on OUTTRAP) to       */
/* indicate that we don't want to actually trap any output */
/* yet. We just want to determine the number of lines of   */
/* output produced.                                        */
/***********************************************************/
X = OUTTRAP(line.,0)

"MYACMD"
No_of_lines = line.trapped            /* Total number of lines of output */
/*********************************************************/
/* Throw away everything except the last 70,000 lines by */
/* setting SKIPAMT                                       */
/*********************************************************/

Skipamt = MAX(No_of_lines - 70000,0)
X = OUTTRAP (line.,'*','CONCAT',skipamt)
" MYACMD"
/****************************************************************/
/* Last 70,000 lines are trapped in line.1 to line.n where n is */
/* the line.0 value. If fewer than 70,000 lines of ouput        */
/* produced, then all of them are trapped.                      */
/****************************************************************/

n = line.0                 /*number actually trapped  - expecting 70,000 */

" execio" n" diskw outdd (stem line. finis" /*Write the trapped lines */

If rc=0 then 
Say n ' lines of data have been written to file OUTDD'
/* ... more processing ... */

" FREE FI(OUTDD)"
exit 0