PIPE NETVIEW

Synonyms

Command Description

The NETVIEW stage specifies to run a NetView®, MVS™, or VTAM® command. The resulting messages are placed in the pipeline. The NETVIEW stage can be placed anywhere in the pipeline specification.

When NETVIEW is not a first stage, NETVIEW invokes a command once for each message on the input stream. Each time NETVIEW receives a message on its input stream, that message becomes the current message. The current message is the message to which NetView's message information functions refer. Thus, GETMLINE, MSGORIGIN(), DSIGETDS, or other message-dependent commands and functions issued by the command invoked by the NETVIEW stage access the message that caused the command to be invoked, exactly as they are if an automation table action or a MSGREAD operation had produced the current message. Also, NetView commands such as MSGROUTE that operate on messages have access to this current message.

Unlike many other stages, the NETVIEW stage does not require an output stream. This means that NETVIEW can be a last stage. Also, if a stage following is disconnected, NETVIEW continues to process as long as it had an input stream.

Streams

Termination Conditions

The NETVIEW stage terminates when it finishes processing its output or when the input stream disconnects.

Operand Descriptions

cmdtext

Specifies the command.

If the NETVIEW stage is the first stage, cmdtext is required.

If the NETVIEW stage is not the first stage, cmdtext is optional. The command is run once for each message delivered by the previous stage. Every time the command runs, the input message becomes the current message during the processing.

If cmdtext is specified, the first blank-delimited token is considered to be the command name. Any additional tokens are passed with the command and become arguments to it.

If cmdtext is not specified, the NETVIEW stage extracts the first line of a message as the command and additional lines, if any, as data to be processed by that command. Any additional messages in the input stream are treated the same way.

In all cases, the original message becomes the current message while the command runs and is then discarded.

If the command name is not a valid NetView command or if no command is found, a return code of 4 is generated and message DSI002I is inserted into the output stream.

CGI

Use the CGI option for a command that can produce either a 3270 display or HTML, to inform the command that HTML is preferred. The direct effect of the CGI option is on the REXX function, CGI(), and causes the function to return a value of 1. CGI cannot be specified with ECHO.

ECHO

When ECHO is specified, the text of the command is written to the pipeline before the command is executed. ECHO cannot be specified with CGI.

MOE

Message on error (MOE) examines the return code from the command. If the return code is not zero, it inserts message DWO369I containing the return code into the stream after any messages the command might have returned. If you do not specify MOE (message on error), return codes from commands are ignored.

NOPANEL

When NOPANEL is specified, the command does not display a full-screen panel. If it attempts to do so, message BNH113W is inserted into the pipeline and the command receives an I/O error code from NetView presentation services.

NOPANEL has restrictions when used with the ATTACH command. See the IBM Tivoli® NetView for z/OS® Command Reference Volume 1 (A-N) or the NetView online help for information about ATTACH.

TAG=tag

The value for TAG is a 1 - 16 character string that the user specifies, and the PIPE processing places in the IFRAUSRC field. This value overlays any previous value for the length given. If the value contains any blanks, commas, or equal signs, you must enclose the value within quotation marks.

Usage Notes

• Although the NetView program does not require system messages to be flagged as command responses in order to be returned to the issuing task, messages that are in response to MVS system commands and are suppressed by MPF, MVS message flooding, and so on must be marked as command responses that descriptor code 5 is the standard method in order to be returned to the NetView stage.
• It is important to distinguish between the output of a command and the results of the command. The NETVIEW stage causes the output of a command to be trapped within the pipeline, but the results, generally, are not. Output consists of messages that are issued in the immediate environment. Results are messages or other actions that are caused by the command, but not immediately or not for the issuing environment.

  For example, the MSG command causes two messages, one output and one result. The DSI039I MSG FROM ... is a result. It is not trapped in the pipeline, even if sent to the same operator where the MSG command was issued. The DSI001I MESSAGE SENT TO... message is output and is trapped by the CORR=CMD parameter to the DSIMQS invocation pipeline for further processing by subsequent stages. Also, read about the CORRWAIT and PERSIST stages; see PIPE CORRWAIT and PIPE PERSIST.

• The following commands are among those NetView commands supported:
  • User-written commands that use the CORR keyword on DSIPUSH, DSIFIND, or DSIMQS assembler macros. See the IBM Tivoli NetView for z/OS Programming: Assembler for more information about these macros.
  • MVS system commands issued from the NetView program.

    When using MVS to address commands to another subsystem (such as JES2), correlation depends upon that subsystem's proper use of the MVS CART message correlators and upon that subsystem's proper routing of response messages. If messages from another subsystem do not appear to be properly processed by your pipelines, contact the support representative for the subsystem being addressed to see if CART support is available on the version of the subsystem you are using.

  • ENDTASK. ENDTASK commands support correlation and can be used in cross-domain pipes for commands between NetView V3R1, or later, programs. ENDTASK commands to and from NetView programs before V3R1 can be executed in a NetView PIPE, but the response does not flow back through the PIPE.
  • RUNCMD. See IBM Tivoli NetView for z/OS Programming: REXX and the NetView Command List Language for more information about using RUNCMD.
  • Other NetView commands that are correlated (those with displayable output). See PIPE HOLE for information on determining if a command has correlated output.
• If you have your own commands (user-written) that produce messages asynchronously, you can modify them so that they are supported by NetView Pipelines. There are two ways to do this:
  • Correlation method.

    If your command solicits data from a DST or other NetView task by sending a command to that task by the DSIMQS macro, you can add an option. This option causes a correlator to be attached to the command that is sent. When the command runs, it can return correlated messages to the originating task by issuing DSIPSS TYPE=OUTPUT.

  • Long running command (LRC) method.

    You can use the long running command support provided by the NetView program to change asynchronous messages into synchronous ones. Use DSIPUSH to make your command an LRC. However your data is returned to the originating task, it must be made available to your resume routine. Usually, this is done by causing a command to run at the originating task which can use DSIFIND to access rstorage that is accessible to the resume routine. The resume routine then issues DSIPSS TYPE=OUTPUT and the resulting messages are considered synchronous.

• If a blank is typed between the last character in the NETVIEW stage and the stage separator, the blank is appended to the stage data. The NetView program ignores the blank, but passes it to another application where it is processed as part of the stage data.
• If you are using the NETVIEW stage to invoke a command procedure that uses the TRAP command, make sure you allow the trapping to occur. You can use the EXPOSE stage after the NETVIEW stage to allow the trap exit to detect messages for trapping.

Return Codes

Other return codes indicate either a storage failure or the return code from the command. If there is a DSI124I message at the system console for this same time frame, you can assume the storage failure caused the non-zero return code (the code depends on the processing stage where the storage failure occurred). Otherwise, the return code was returned by the command.