PIPE (NCCF)

Command Description

NetView® Pipelines help you solve a complex problem by dividing it into a series of smaller steps. Each step or stage solves one part of the overall problem. Some stages read data from system sources, such as files on DASD or variables in command procedures. Other stages filter and refine that data in some way. Still other stages export (output) data from the pipeline. You can connect stages in logical sequence until they collectively cover all steps required to solve your problem.

You determine the function of each stage by coding a stage as described in this chapter.

You determine the function of each stage by coding a stage as described in the IBM® Tivoli® NetView for z/OS® Programming: Pipes book. A stage and its related parameters is called a stage specification.

When you have completed a series of stage specifications, you can run them with the PIPE command. The PIPE command identifies the series of stage specifications you want to run and, through parameters, controls other run characteristics that are described later. A series of stage specifications and the instructions for connecting them is called a pipeline specification. A PIPE command containing multiple pipeline specifications, labels, and end characters is called a complex pipeline. A simple pipeline contains a pipeline specification, but does not contain labels or end characters.

 HELP PIPE SYNTAX

 HELP PIPE stage_name

See PIPE Stages for an alphabetic listing and brief summary of each PIPE stage.

Operand Descriptions

DEBUG

Generates connection and data stream trace information that can be used to debug pipelines. DEBUG, when used as a PipeOption, must have one of the following items specified:

1

Produce debug output for all pipeline stages. This is the same as coding (DEBUG) on each stage.

2

Produce additional debug information whenever a BNH155E message is generated. BNH155E indicates that the pipeline is clogged. The additional information produced by DEBUG 2 can help you diagnose the clog.

Both DEBUG 1 and DEBUG 2 can be specified in the same pipeline specification.

For more information on the DEBUG option see Debugging NetView Pipelines.

END

The end character allows multiple, simple pipelines to operate within a complex pipeline. The pipeline specification, included after the end character, operates independently of the pipeline specified before the end character. The end character, with stage labels, and stages with multiple input or output streams is used to create complex pipelines. For information on creating complex pipelines, see Complex Pipelines.

The valid value of END can be a character acceptable for STAGESEP, but the value cannot be the same value as STAGESEP or ESC in the same PIPE command.

If you want to include the end character within your pipe where it must not be interpreted as an end character, you can either include the ESC character immediately before it or use the self escape technique. Two side-by-side END characters resolve to one character taken literally. For example, if your ESC character is defined as % and your END character is defined as ?, use either of the following examples:

PIPE (END ?) LITERAL 'MY END CHARACTER IS ??' 
     |   CONSOLE

PIPE (ESC % END ?) LITERAL 'MY END CHARACTER IS %?' 
     | CONSOLE

The following text is displayed on the console:

MY END CHARACTER IS ?

ESC

Indicates that the character following the specified character is treated literally when the pipeline specification is parsed. For example, if you specify STAGESEP | ESC % as options and the string ABC%|XYZ is encountered in the pipeline specification, then the % character is removed and the following | character is not treated as a stage separator. This leaves the string ABC|XYZ in your stage specification.

The valid value of ESC is that of any character acceptable for STAGESEP, but it cannot be the same value as that used for STAGESEP or END in the same PIPE command.

Alternatively, you can use the stage separator character to self escape itself. Two side-by-side separators resolve to one such character taken literally. For example:

 PIPE LITERAL 'MY CHAR IS ||' | CONSOLE

Results in the display of the following text:

 MY CHAR IS |

label

The label must be 1 - 8 alphanumeric characters followed by a colon. A label can be followed by blanks. Although you can assign a label to any stage, label is only useful when used with the end character and stages with multiple output streams to create complex pipelines. For information on creating complex pipelines, see Complex Pipelines.

LOWQENAB

Commands that are queued at a low priority are not processed until pipeline processing is complete. Commands blocked include low-priority commands from the automation table. Blocking low-priority commands assures that the commands are processed first in-first out (FIFO).

High-priority commands pre-empt pipeline processing.

When LOWQENAB is specified, pipeline processing is temporarily suspended whenever any command is queued. Even low-priority commands pre-empt pipeline processing.

LOWQENAB affects only the pipeline where it is specified. All other automation and low priority commands continue to run in FIFO order.

NAME

Indicates the name of this pipeline. The name given is used in various messages about the processing of the pipeline and can be an aid in debugging.

pipename

The value is 1 - 8 alphanumeric characters. The default value is PIPE.

stage_specification

A NetView stage and its operands. This can be a label previously defined in the pipeline that is used as a connector in a complex pipeline. At least one stage or connector label must be specified.

STAGESEP

Specifies the character used to separate the stages in a PIPE command.

The STAGESEP, END, and ESC characters must be different within a single pipe specification.

value

Is a single-byte, nonalphanumeric EBCDIC character except blank, null, ), (, @, #, and $.

The default stage separator character is X'4F'. On American and English 3270 displays, X'4F' is represented as a vertical bar (|). In other countries or on some workstations, X'4F' can be displayed as an exclamation mark or a split vertical bar.

Usage Notes

• For the PIPE command and its stages, a delimiter can be any character except alphanumeric characters, parentheses, blanks, nulls, and national characters (@, #, and $). The maximum length for a delimited string is 255 characters. Multiple delimited strings must be separated by blanks. In the formats shown, the delimiter is a ⁄.
  Ensure that delimited strings do not contain:

  • The delimiter character in use
  • The stage separator (unless escaped)
  • The escape character (unless escaped)
  • The end character (unless escaped)
• The presence of the escape character has no effect on characters that have special meaning to individual stages. For example, do not use the escape character within a delimited string in an attempt to include the delimiter character in the string.
• If running DBCS, be careful of what STAGESEP character is used. The NetView program determines the hexadecimal equivalent of the STAGESEP character and then scans the string until it finds it again. The scan does not determine if the string is part of a DBCS character. The next occurrence of the string ends the stage command. See the VAR stage for more information. See PIPE VAR and PIPE $VAR for more information.
• See the individual stages for other usage notes that apply.

Return Codes

Return Code

Meaning

 0

The pipeline ran successfully.

 8

An option field error occurred.

12

A PIPE syntax error occurred, or a stage separator character was used improperly.

16

A stage specification error occurred.

20

A storage failure occurred during PIPE interpretation.

24

The pipeline is clogged. A deadlock occurred during pipeline processing.

For information on debugging clogged pipeline conditions see Debugging NetView Pipelines.

-1

An unrecoverable error occurred during processing, it was possibly a looping condition.

-5

A RESET condition occurred.