IBM Tivoli NetView for z/OS, Version 6.2

PIPE TSO

Syntax

Read syntax diagramSkip visual syntax diagram
TSO

|--TSO--+---------------+--+--------------+---------------------|
        '- --(--ECHO--)-'  '- tso_command-'   

Command Description

TSO transfers a command to a NetView® TSO server, which is a batch job submitted by NetView or a started task. The command is executed and the results returned. Specify CORRWAIT to follow TSO to enable the return of command responses.

Commands can be passed on the stage or on the input stream. If tso_command is not specified and a multiline message is received on the primary input stream, the first line of the message is considered the TSO command and all other message lines are passed as the data of that command. If tso_command is specified, that command is executed for each input message or only once if there is no primary input stream.

When TSO has a primary input stream and no tso_command is specified, the command to be executed is read from the primary input stream. The message input to the TSO stage at the time the TSO command is scheduled is passed to the TSO server for execution. The message data is contained in a sequential file userid.NVCMDIN that is allocated as DD NVCMDIN. NVCMDIN is not allocated if there is no current message for the command.

A secondary input stream can be connected to TSO. The secondary input stream must contain records that contain the TSO user ID optionally followed by the TSO server job member name. The user ID and server job member name must be separated by at least one blank. If the server job member name is not specified, it defaults to CNMSJTSO. The default server is the server specified for this operator by the START command.

If a secondary input stream is not connected, the TSO server started for the issuing operator is used. The default operator is specified on the START command.

The TSO server job member name is specified on the START command with the TSOSERV and MEM keywords.

Each primary input stream message is associated one-for-one to each secondary input stream message. That is, for each primary input stream message there can be a secondary input stream message indicating the TSO server where the primary input stream messages are to be sent. If either the primary or secondary input stream is exhausted before the other, the remaining input on the active input stream is discarded. If no secondary input stream is defined, all messages on the primary input stream are sent to the TSO server started for the issuing operator.

Figure 1. TSO Command Flow
TSO Command Flow

Figure 1 shows an example execution of a TSO command. Within a pipeline a NETSTAT command is duplicated using the DUP stage. Multiple NETSTAT commands become the primary input stream to the TSO command. From elsewhere in the pipeline, a secondary input stream is connected to the TSO stage. This secondary input stream contains records with the TSO user ID followed by a TSO server job member name.

The TSO stage sends the NETSTAT command to all TSO server jobs on the secondary input stream. Responses are returned from TSO to the CORRWAIT stage following the TSO stage.

Streams

Stream Type Number Supported
Input 2
Output 2

Termination Conditions

TSO terminates when the primary input stream and the primary output stream are disconnected. If followed by CORRWAIT, CORRWAIT automatically ends when the TSO command is completed and the response has been received.

Operand Descriptions

ECHO
Write the command to the primary output stream prior to the execution of the command.
tso_command
A TSO line mode command to be invoked at the TSO server. Tso_command is required when TSO has no input stream and is otherwise optional.

If tso_command is specified, the command is invoked once if the TSO stage has an input stream. Otherwise, the command is invoked when an input message is passed to the TSO stage.

If tso_command is not specified, the commands to be invoked are read from the input stream.

Note: Long running commands, such as IPTRACE, and commands requiring a dialog, such as ACCOUNT, are not supported.

Usage Notes

  • Command responses are delayed until command completion. For example, a TSO command that issued a message every 2 seconds and runs for 10 seconds delays 10 seconds before issuing 5 messages together.
  • Command execution is single threaded for each server.
  • Commands requiring a dialog are not supported. However, data for a dialog can be assembled into a multiline message. This multiline message can be used to drive a TSO REXX procedure managing the dialog within TSO.
  • Command authority is checked prior to and after submitting the command.
    Prior to submission authority is checked for the pipe stage and for the verb of the TSO command. The verb of the TSO command is the first blank delimited token. To permit only BOSS to use the TSO stage, code the following statements:
    PROTECT *.*.DSIPITSO
    PERMIT BOSS *.*.DSIPITSO

    The verb of the TSO command is treated as the value of the PROTECT keyword VERB for authority checking purposes. For example, if you want to prevent operators from issuing a PIPE TSO IPTRACE command, code the following statements:

    PROTECT *.*.DSIPITSO.VERB.IPTRACE
     
    The specified server is treated as the value of the PROTECT keyword TSOSERV for authority checking purposes. For example, to prevent operators from using server USER1 in combination with the started job SERVJOB1, code the following statements:
    PROTECT *.*.DSIPITSO.TSOSERV.USER1/SERVJOB1
     
    See the START command in the NetView online help for additional information on started jobs.
    Note: The TSO stage cannot resolve TSO synonyms. All command synonyms must be protected.

    TSO performs command authority checking using the same rules that apply when the TSO user name is directly logged-on.

Return Codes

A secondary output stream can be connected to receive command response codes. Each code begins with a 10-digit, 0-padded, signed number. Nonzero codes indicate an error and are followed by a space and keyword indicating the source of the error such as +0000000100 PPI.

The keyword can be one of the following keywords:
AUTHCHK
An error occurred during authorization checking. AUTHCHK is followed by a DSIKVS return code indicating the error. See IBM Tivoli NetView for z/OS Programming: Assembler for DSIKVS return codes.
COMMAND
Indicates that the preceding is the return code resulting from the execution of the TSO command. Refer to the appropriate publication for the TSO command being executed for further information.
INITERR
An error occurred during TSO stage initialization.
+0000000122
Indicates that the TSO server is not started or that a TSO server name was not specified on the stage.
PPI
An error occurred connecting to the NetView Program-to-Program Interface or when sending the command to the destination.
+0000000032
Indicates that an out of storage error occurred.
+0000000100
Indicates a system abend occurred within PPI processing. This can occur when the Program-to-Program interface is canceled.
+0000000104
Indicates that a user abend occurred in PPI processing.
See the IBM Tivoli NetView for z/OS Application Programmer's Guide for information on additional Program-to-Program Interface send, receive, transaction, and initialization return codes.
TSO
An error occurred in TSO operations supporting the command invocation.
-0000000003
Indicates that the TSO command does not exist.
TSOSERV
An error occurred when trying to identify the TSO server.
+0000000002
Indicates that an incorrect TSO server name was specified.
+0000000004
Indicates that the TSO server was not found.
+0000000008
Indicates that TSO user was not found.
+0000000012
Indicates that communications cannot be established with the PPI.
+0000000016
Indicates that the SAF product denied the requester access to the TSO server.
+0000000020
Indicates that a storage problem occurred during TSO server identification.

Example: Discover TSO Stacks Serving a User

In the following example, the TSO stacks serving a TCP user are listed:

/* REXX Example usage of TSO stage.                     */
/* Purpose: to discover which of several TCP stacks is  */
/*          serving a given user.                       */
/*                                                      */
/* Input:  TCP  User ID                                 */
/*                                                      */
/* Output: stack name and current state               	  */
/*         (multiple lines are shown for user ids using */
/*          multiple ports)                             */
/*                                                      */
/* Assumptions:                                         */
/*      1.  the TCP stack name or other mnemonic  used  */
/*          as a member name (copy of CNMSJTSO) for     */
/*          the TSO servers. See help for START TSOSERV.*/
/*                                                      */
/*      2.  authority has been granted to use any server*/
/*          found. (Otherwise, further filtering can    */
/*          be done. See note 1, below.)                */
/*                                                      */
/*      3.  TSO server has PROFILE MSGID in effect.     */
/* ---------------------------------------------------- */
 ADDRESS NETVASIS
 arg theUser
 IF  words(theUser) <> 1  THEN
  DO;
    say 'User ID requried'
    EXIT 12
  END;
 ELSE  theUser = left(theUser,8)

 'PIPE (NAME SRVRLIST)',
 '| NETV LIST STATUS=TSOSERV', /* Obtain list of all servers.   */
 '| SEPARATE DATA',            /* sep & discard label lines.
  */
 '| SORT 21.8',                /* sort on member (= stack name).*/
       ,                       /* LOCATE?  See NOTE 1, below    */
 '| DELDUPES KEEPFIRST 21.8',  /* keep one of each.             */
 '| EDIT   WORD 2 NEXT',       /* build record: tso userid and  */
          'WORD 3 NEXTWORD',   /* member name from each line.   */
 '| STEM STACKS.'              /* save these to feed TSO stage  */
                               /* on its secondary input, below.*/

 'PIPE (NAME MULTSTAT END %)',
 '| LITERAL /NETSTAT/',        /* creating a command            */
 '| DUP *',                    /* make copiesindefinitely: NOTE2*/
 '| A: TSO',                   /* read destinations from A below*/
 '| WAIT 90',                  /*   wait plenty                 */
 '| SEPARATE',                 /* can't use SEP DATA            */
 '| LOCATE 1.10 /EZA0185I/',   /* get just the data lines       */
 '| LOCATE 10.10 /'theUser'/', /* and lines with our user's name*/
         ,               /* Now that we have data about our user*/
         ,               /* where did it come from?  The answer */
         ,               /* is in the attributes:  JOBID        */
 '| EDIT JOBID  1 ',           /* Build msg with member name,   */
        'word 2 NW ',          /*  user's name, and             */
        'word 6 NW ',          /*  current state.               */
 '| CONS',                     /*                               */
 '| TAKE LAST 1',              /*  IS there a last one?         */
 '| PIPEND 2',                 /*  IF so, make rc = 2           */
        ,                 /* ------ end of main pipeline ------ */
 '% STEM STACKS.',             /* first stage: read server list */
 '| A:'                        /*  feed this to TSO secondary   */

 IF  rc <> 2  THEN  say theUser 'not found.'

/* -------------------------------------------------------------*/
/* NOTE 1 If desired, a LOCATE stage c be inserted at this  */
/*        point to select one or more TSO userids.              */
/*        You might want to do this, if security requires that  */
/*        a general user be limited in choice of servers to use.*/
/*                                                              */
/* NOTE 2 Infinitely many copies?!?   Not really, since the TSO */
/*        stage has secondary input stream (servers to use), it */
/*        will accept as many commands as there are servers feed*/
/*        to it.  After the secondary input stream disconnects, */
/*        TSO stage disconnects and the copying ends.           */
/* ------------------------------------------------------------ */


Feedback