IBM Tivoli NetView for z/OS Programming: Pipes - IBM notice

PIPE STEM and PIPE $STEM
Usage Notes
228 Programming: Pipes
The default for (number) is zero (0).
FROM
Indicates a starting point for access to the stem variables. If FROM is specified,
frNumber must also be specified. FROM can be used on stages that are first or
not first.
frNumber
A positive number. When STEM is a first stage this is the number of the first
stem variable written to the output stream. When STEM is not a first stage,
this is the number of the first variable stored. Do not specify both FROM and
APPEND.
v When STEM is the first stage of a pipeline specification, the following conditions
apply:
– The maximum size of a message buffer output from the STEM stage is 32,000
bytes. Message buffers exceeding 32,000 bytes are truncated to 32,000 bytes.
– If the variable specified on the STEM stage has a record count that is not
valid, the pipeline is rejected with message DWO206I, and the pipeline ends.
The record count of the STEM variable must be zero, or positive, and less
than 10.000,000.
v When STEM is not the first stage of a pipeline specification, the following
conditions apply:
– The value of the count variable (name with '0' appended) is initialized to zero
very early in pipeline initialization (unless APPEND is specified). If your
pipeline fails to run because of an error or a RESET condition, this variable
might have a value of zero, even though your pipeline was not processed.
Likewise, if messages are not processed by STEM, the value of the count
variable is zero.
– Input messages to the STEM stage are inspected for message lines as follows:
- An input stream containing a single message line causes two STEM records
to be saved: one STEM variable containing the message, and one STEM0
containing the record count.
- An input stream containing a 10-line MLWTO causes 11 STEM records to
be saved: one for each line of the MLWTO, plus one for STEM0 containing
the record count.
- An input stream consisting of a single-line message and a 10-line MLWTO
causes 12 STEM records to be saved and so forth.
v A much more efficient and predictable behavior is obtained when using
COLLECT with the COMMON option. If STEM is a first stage, COLLECT must
be specified on the STEM stage. If STEM is not a first stage, a COLLECT stage
must precede the STEM stage.
For example, if one task is updating the common global stem X. and your task
is reading it, the following example might get some of the updated X. values
and some of the older values:
PIPE STEM (COMMON) X. | CONSOLE
However, the following command gets all of the older values or all of the
updated values.
PIPE STEM (COMMON) X. COLLECT | CONSOLE
v STEM ignores the structure of the messages it receives. Thus, 10 one-line
messages set 10 stem records and one 10-line message also sets 10 stem records.