NETVIEW:
 
|--NETVIEW--+--------------------------------------+------------>
            '-(-+----------+-+---------+-+-----+-)-'
                '-+-CGI--+-' '-NOPANEL-' '-MOE-'
                  '-ECHO-'
 
>--+----------+--+-----+----------------------------------------|
   '- cmdtext-'  '-TAG-'
 

Stage Name	Synonym
NETVIEW	NETV

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 NETVIEW were to be disconnected, NETVIEW continues to process as long as it had an input stream.

Stream Type	Number Supported
Input	1
Output	1

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

cmdtext

Specifies the command.

If NETVIEW is the first stage, cmdtext is required.

If NETVIEW 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 will not be allowed to display a full-screen panel. If it attempts to do so, message BNH113W will be inserted into the pipeline and the command will receive 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

The value for TAG is a 1 - 16 character string, which is placed in the IFRAUSRC field of each correlated response. 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.

• 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.

• The following 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, if extended multiple console support (EMCS) consoles are being used.

    For more information about EMCS consoles, see the MVSPARM statement in the IBM Tivoli NetView for z/OS Administration Reference.

    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. NetView will ignore the blank, but passes it to another application where it can be processed as part of the stage data.

The following return codes are valid only when the MOE operand is used.

Return Code

Meaning

-4

Installation exit 03 generated USERDROP.

-500 to -599

Failure attempting to call installation exit 03. Please report specific return code to the IBM Software Support.

-108

Command is type=I or type=P.

-112

Command search failure, usually because the command is too long.

-116

ACCESS not authorized. Command authorization restrictions prevent processing.

-120

Command is type=D.

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.

---

[ Top of Page | Previous Page | Next Page ]