IBM Tivoli NetView for z/OS, Version 6.2

Getting Started with NetView Pipelines

The PIPE command specification consists primarily of options and stage specifications with a stage separator between each stage. The default stage separator character is usually a vertical bar (|) on 3270 terminals, but might be a split vertical bar (¦) on workstation terminals.

The following examples use several pipeline specifications to manipulate messages in different ways. They are intended to show basic pipeline possibilities without exploring all the filters and device drivers available. For more information on other filters, see NetView Pipeline Filters. For information on device drivers, see NetView Pipelines Device Drivers.

As an example, consider two fictitious people and a fictitious event: Pete and Sam planning their annual vacation. They have created a member named WISHLIST in a partitioned data set that is associated with the DSIPARM ddname. WISHLIST contains travel information, including sites to see and various attractions. Pete and Sam are working in an MVS™ environment.

Pete decides to write a PIPE command that will list all the destinations on their list.

He enters on the command line:

 PIPE <  WISHLIST | CONSOLE

The < (From Disk) stage accesses a disk file and writes its contents to the pipeline, thus bringing data into the pipeline. The complete stage specification for the < (From Disk) stage is < WISHLIST, which consists of the stage name, <, and its operand, WISHLIST.

The CONSOLE stage displays the results to the operator console. The complete CONSOLE stage specification is CONSOLE, because none of its operands are used in this example. The < (From Disk) and CONSOLE stages are both device drivers.

The output to Pete's operator console looks like this:

 NCCF                      N E T V I E W    CNM19 PETE     03/26/10 13:10:00
 * CNM19    PIPE <  WISHLIST | CONSOLE
 | CNM19    CAIRO, EGYPT                                     AFRICA
 | CNM19    CASABLANCA, MOROCCO                              AFRICA
 | CNM19    KRUGER PARK                                      AFRICA
 | CNM19    NILE RIVER                                       AFRICA
 | CNM19    BANGKOK, THAILAND                                ASIA
 | CNM19    GREAT WALL, CHINA                                ASIA
 | CNM19    TOKYO, JAPAN                                     ASIA
 | CNM19    YANGTZE RIVER                                    ASIA
 | CNM19    ALICE SPRINGS                                    AUSTRALIA
 | CNM19    PARIS, FRANCE                                    EUROPE
 | CNM19    RHINE RIVER                                      EUROPE
 | CNM19    ROME, ITALY                                      EUROPE
 | CNM19    GRAND CANYON PARK, ARIZONA, USA                  N. AMERICA
 | CNM19    MISSISSIPPI RIVER                                N. AMERICA
 | CNM19    NEW YORK, NEW YORK, USA                          N. AMERICA
 | CNM19    YOSEMITE PARK, CALIFORNIA, USA                   N. AMERICA
 | CNM19    DANALI PARK, ALASKA, USA                         N. AMERICA
 | CNM19    AMAZON RIVER                                     S. AMERICA
 | CNM19    ANDES MOUNTAINS                                  S. AMERICA
 | CNM19    RIO DE JANIERO, BRAZIL                           S. AMERICA
 ???

Pete is an avid canoeist, so he decides to change the pipeline specification to limit his selection of vacation spots to those with rivers. He accesses the same disk file shown in the previous example, but he now enters this PIPE command:

PIPE  <  WISHLIST
      | LOCATE /RIVER/
      | LITERAL /Pete's canoeing adventures/
      | CONSOLE

Actually, if Pete had entered that command on a command line, he would have been limited to three lines and would have entered it in landscape form, but it is shown here in portrait form for ease of reading.

Pete's command uses the LOCATE stage to select all messages that contain the character string RIVER. Messages not selected are discarded from the pipeline and are no longer available for subsequent processing by other stages. To indicate that the choices are his, Pete uses the LITERAL stage to add a comment to the pipeline. The LITERAL stage writes text to the pipeline ahead of messages already there. As before, the results are displayed to the operator console, using the CONSOLE stage.

The specification for the LOCATE stage is LOCATE /RIVER/. The operand RIVER is supplied as a search argument for the stage to use when examining messages. The slash (/) character is the string delimiter.

The specification for the LITERAL stage is:

LITERAL /Pete's canoeing adventures/

The operand (Pete's canoeing adventures) represents the text to be placed in the pipeline.

In this example, the <, LITERAL, and CONSOLE stages are device drivers, whereas the LOCATE stage is a filter.

The results are shown as they might appear on the operator console. Because NETVASIS was not specified, the lowercase literal value becomes uppercase when it is displayed.

 NCCF                     N E T V I E W    CNM19 PETE      03/26/10 13:20:00
* CNM19    PIPE < WISHLIST | LOCATE /RIVER/ | LITERAL /PETE'S CANOEING
           ADVENTURES/ | CONSOLE

| CNM19    PETE'S CANOEING ADVENTURES
| CNM19    NILE RIVER                                       AFRICA
| CNM19    YANGTZE RIVER                                    ASIA
| CNM19    RHINE RIVER                                      EUROPE
| CNM19    MISSISSIPPI RIVER                                N. AMERICA
| CNM19    AMAZON RIVER                                     S. AMERICA

Sam, a hiking enthusiast, changes the pipeline specification to display which destinations are parks. He plans to budget his trip carefully and decides to eliminate destinations far from his home, such as Asia, Africa, and Australia.

Sam enters this command:

PIPE <  WISHLIST
      | LOCATE /PARK/
      | NLOCATE /AFRICA/ /ASIA/ /AUSTRALIA/
      | LITERAL /Sam's hiking choices/
      | CONSOLE

Sam changes the LOCATE stage to select all messages that contain the character string PARK. He adds the NLOCATE filter stage to his pipeline to discard messages for the continents he is not interested in visiting. All messages not discarded by NLOCATE remain in the pipeline for further processing.

The stage specification for the NLOCATE stage is NLOCATE /AFRICA/ /ASIA/ /AUSTRALIA/. The three character strings, AFRICA, ASIA, and AUSTRALIA are the search arguments.

Note: The LITERAL stage appears after the LOCATE and NLOCATE stages because:

It is undesirable for the text string Sam's hiking choices to be subjected to filtering done by the LOCATE and NLOCATE stages.
LITERAL writes the text string in front of messages already present in the pipeline.

In this example, the <, LITERAL, and CONSOLE stages are device drivers, and the LOCATE and NLOCATE stages are filters.

The results are shown as they might appear on Sam's console:

 NCCF                     N E T V I E W    CNM19 SAM       03/26/10 13:30:00
* CNM19    PIPE < WISHLIST | LOCATE /PARK/ | NLOCATE /AFRICA/ /ASIA/
           /AUSTRALIA/ | LITERAL /SAM'S HIKING CHOICES/ | CONSOLE

| CNM19    SAM'S HIKING CHOICES
| CNM19    GRAND CANYON PARK, ARIZONA, USA                  N. AMERICA
| CNM19    YOSEMITE PARK, CALIFORNIA, USA                   N. AMERICA
| CNM19    DANALI PARK, ALASKA, USA                         N. AMERICA

After much discussion, the young men decide to combine choices and add one other filter (TAKE FIRST 1) as well. Pete enters this command:

 PIPE <  WISHLIST
      | LOCATE /RIVER/ /PARK/
      | NLOCATE /AFRICA/ /ASIA/ /AUSTRALIA/
      | TAKE FIRST 1
      | LITERAL /OUR FINAL VACATION CHOICE/
      | COLLECT
      | CONSOLE

They changed the LOCATE stage to select messages that contain either the word RIVER or PARK. The NLOCATE stage subsequently sees only messages containing RIVER or PARK and from those messages discards all that contain ASIA, AFRICA, or AUSTRALIA.

Next, the TAKE stage selects the first message remaining in the pipeline after all the previous stages are completed. This is a message showing a river or park that is not in Asia, Africa, or Australia.

The complete specification for the TAKE stage is TAKE FIRST 1, which indicates that the first message is selected from the input stream and all other messages are discarded from the pipeline.

Pete changes the text string used by the LITERAL stage and also adds the COLLECT stage to gather all messages in the pipeline into one multiline message before displaying them.

In this example, the <, LITERAL, and CONSOLE stages are device drivers, and the LOCATE, NLOCATE, COLLECT, and TAKE stages are filters.

The PIPE command generates this display on Pete's console:

 NCCF                     N E T V I E W    CNM19 PETE      03/26/10 13:50:00
 * CNM19    PIPE < WISHLIST | LOCATE /RIVER/ /PARK/ | NLOCATE /AFRICA/ /ASIA/
            /AUSTRALIA/ | TAKE FIRST 1 | LITERAL /OUR FINAL VACATION CHOICE/ |
            COLLECT | CONSOLE

 | CNM19
 OUR FINAL VACATION CHOICE
 RHINE RIVER                                      EUROPE

As a final step, Sam writes and runs a small command procedure, WISHCLST, written in the NetView command list language. This command procedure uses PIPE commands to write the final vacation choice to a command procedure variable, then read the variable, and display the results to a console.

The command procedure is in Figure 1. The output from the procedure in Figure 1 is shown in Figure 2.

Figure 1. A Pipeline Invoked from a Command Procedure Called WISHCLST

 WISHCLST CLIST
 &CONTROL ERR
 *
 *********************************************************************
 ** THIS CLIST USES THREE PIPE COMMANDS.                            **
 ** -  THE FIRST WRITES A MESSAGE TO A CLEARED SCREEN.              **
 ** -  THE SECOND WRITES A MESSAGE TO A CLIST VARIABLE.             **
 ** -  THE THIRD READS THE VARIABLE AND DISPLAYS THE RESULTS.       **
 *********************************************************************
 *
 *********************************************************************
 ** WRITE MESSAGE TO TERMINAL USING PIPE COMMAND                    **
 *********************************************************************
 PIPE LITERAL /WISHCLST IS PROCESSING/ +
     | CONSOLE CLEAR
 *********************************************************************
 ** CHOOSE A VACATION DESTINATION USING THE PIPE COMMAND TO         **
 ** READ RECORDS FROM A DISK FILE INTO THE PIPELINE,                **
 ** MANIPULATE THEM AND STORE ONE RESULTING MESSAGE IN THE          **
 ** VARIABLE NAMED VACVAR.                                          **
 *********************************************************************
 PIPE < WISHLIST     +
     | LOCATE /RIVER/ /PARK/  +
     | NLOCATE /AFRICA/ /ASIA/ /AUSTRALIA/  +
     | TAKE FIRST 1  +
     | VAR VACVAR
 *********************************************************************
 ** READ VARIABLE NAMED VACVAR INTO THE PIPELINE AND ADD            **
 ** 'VACATION CHOICE' TEXT AHEAD OF IT, THEN DISPLAY.               **
 *********************************************************************
  PIPE VAR VACVAR     +
      | LITERAL /VACATION CHOICE/  +
      | COLLECT +
      | CONSOLE
 *********************************************************************
 ** WRITE RETURN CODE INFORMATION TO TERMINAL AND EXIT CLIST        **
 *********************************************************************
 &WRITE RETURN CODE = &RETCODE
 &EXIT
 *************************** BOTTOM OF DATA **************************

Figure 2. Pipeline Output from WISHCLST Command Procedure. Created by the pipeline in Figure 1.

WISHCMD is processing
/*REXX WISHCMD                                                     */
/*  This procedure uses three PIPE commands
    - The first writes a message to a cleared screen
    - The second writes a message to a REXX variable.
    - The third read the variable and display the result.
 ------------------------------------------------------------------*/
ADDRESS NETVASIS        /* Prevent literals from being upper cased */

'PIPE (NAME WISHCMD1)',              /* Simple message to operator */
'| LITERAL /WISHCMD is processing/',
'| CONSOLE CLEAR'

/*---------------------------------------------------------
  Choose a vacation destination using the PIPE command to
  read records from a disk file into the pipeline,
  manipulate them and store one resulting message in the
  variable named VACVAR.
 ------------------------------------------------------------------*/
 'PIPE (NAME WISHread)',
 '| < WISHLIST',
 '| LOCATE /RIVER/ /PARK/',
 '| NLOCATE /AFRICA/ /ASIA/ /AUSTRALIA/',
 '| TAKE FIRST 1',
 '| VAR VacVar'
/*---------------------------------------------------------
 Read variable named VACVAR into the pipeline and add
 'vacation choice' text ahead of it, then display.
 ------------------------------------------------------------------*/
 'PIPE (NAME WISHOUT)',
 '| VAR VACVAR',
 '| LITERAL /Vacation Choice/',
 '| COLLECT',
 '| CONSOLE'
 EXIT 0
/*------------------------* End of WISHCMD *-----------------------*/

Feedback