PIPE CORRWAIT

Syntax

CORRWAIT

Synonyms

Stage Name	Synonym
CORRWAIT	CORR, WAIT

Command Description

The CORRWAIT stage allows time to pass while asynchronous messages generated by the previous stage are returning to the pipeline. For every message processed by CORRWAIT, the timeout value is reset to allow up to n seconds between messages where n is determined by the interval parameters.

Asynchronous or delayed messages are those which return to the NetView® program from commands running in another task (SWITCH, for example), or at another NetView system. When asynchronous responses are expected from any command issued in a pipe NETVIEW or VTAM® stage, the next stage must be CORRWAIT. Otherwise, the stages in between do not see the asynchronous messages, and results are unpredictable.

The CORRWAIT stage can be used as a first stage (to provide a definite waiting period) or following a stage generating asynchronous messages.

Streams

Stream Type	Number Supported
Input	1
Output	2

Termination Conditions

CORRWAIT normally terminates when the preceding stage completes. For example, if you enter:

PIPE NETV RMTCMD LU=CNM02,LIST XXX|CORRWAIT 60|STEM RMTDATA.

RMTCMD completes its local processing in less than a second, but processing of the stage continues, first at a DST, next in the network, then at a remote NetView. LIST produces one or more messages, which CORRWAIT captures and writes to its primary output, STEM RMTDATA., and then CORRWAIT resets its timeout value.

When the LIST stage completes, CORRWAIT is notified and the wait ends immediately. Functionally, it is as if the preceding stage did not complete processing until the stage at the remote NetView system completed. At that point, the NetView stage disconnects and CORRWAIT ends with its input stream disconnected.

CORRWAIT processing is the same when more than one command is issued by the preceding stage. For example, if you create a stem variable containing a series of LIST DST= commands for all your DSTs and then issue:

PIPE STEM LISTCMDS.|NETVIEW|CORRWAIT 20| ...

Each LIST stage queues a request for data to a DST and ends, but CORRWAIT continues to wait until each of the queued requests completes.

Notification support to CORRWAIT is not available for many VTAM and MVS™ commands. Because this support is not available, these commands are considered never-ending. CORRCMD and CCDEF can be used to handle VTAM and MVS commands.

You can define a secondary output for CORRWAIT if you want CORRWAIT to process in a different manner. CORRWAIT produces a message on its secondary output stream each time a completion event occurs. When a secondary output stream is defined, CORRWAIT continues to wait only while the secondary output stream remains connected.

The messages passed to the secondary output stream consist of a plus or minus sign followed by a 10-character, right-aligned-, zero-padded completion code. This completion code is followed, beginning in position 13, by information which might be useful in debugging your pipeline. The debugging information includes:

The domain ID where the event occurred
TVBOPID where the event occurred
The command completing, if applicable

Attention: Domain ID, TVBOPID, and the command completing are not intended as a programming interface, because formats might change and additional data might be included in the future. Use these only for problem determination.

The completion codes are based on the type of event, not the return code from a command.

Completion Code: Event
+0000000000: A command thread completed (see note).
+0000000008: A timeout occurred.
+0000000012: A GO command was issued.
+0000000016: A task executing a thread terminated.
+0000000032: An ABEND occurred on a task that was executing a thread.
-0000000005: A RESET occurred on a remote task that was executing a thread.

Note: A command thread is any command executing under the control of the pipeline or any secondary command created or queued by such a command. When secondary commands create additional commands, these are not counted individually, rather, the completion of the last secondary command is reported as the completion of its parent secondary event.

Operand Descriptions

interval

Specifies the maximum time, in seconds, between messages before messages are no longer collected. Valid values are in the range of 1 - 10,000,000. The default is 1.

An asterisk (*) can be specified for interval. When an asterisk is specified, CORRWAIT never times out. The following conditions end the wait:

A GO command
A RESET command
A PIPEND pipe stage
Secondary output disconnect
Other conditions that end a wait

seqWait

The second number (after interval) specifies the time in tenths of a second to wait between messages, after the first message. This is to allow the timeout to change after responses have begun to flow. Valid values are in the range of 0 - 10,000,000. The default is the same time period (ten times the value of the argument) as the interval. Note that, for purposes of determining the "first" message, command echos are ignored, as are certain (unseen) internal NetView flows.

aftMlWait

The third number (after seqWait) specifies the time in tenths of a second to wait following receipt of the first multi-line message. This allows you to change the wait period when you know the pattern of responses. Valid values are in the range of 0 - 10,000,000. The default is the same time period as was specified for the seqWait.

MOE

Message on error (MOE) inserts message DWO369I containing a return code into the stream when a timeout occurs, after any messages the command might have returned.

CORRWAIT recognizes an artificial timeout if the operator enters the GO command while the wait is in effect.

NOSLOGR

Suppresses the recording of command responses in the system log and the Canzlog log. Any response that is received after the wait is terminated (such as by timeout) is not affected.

Usage Notes

The display of W in the upper right of the operator's screen indicates that CORRWAIT is actively waiting for messages.
Another stage must follow CORRWAIT in order to actually wait for a specific interval of time.
When routing a PIPE command to another domain (using RMTCMD), ensure that your CORRWAIT values are long enough. The system discards asynchronous, correlated messages that arrive after a CORRWAIT times out.
When a terminating stage (TOSTRING or TAKE) is used to end a wait, the terminating stage must immediately follow CORRWAIT. This applies only to MVS or VTAM commands, because NetView commands automatically end CORRWAIT when the commands end.
For performance considerations when issuing a command to MVS or VTAM, use a stage containing terminating conditions (for example, TOSTRING or TAKE FIRST) after a CORRWAIT stage. Terminating conditions end data streams early in the pipeline and allow the pipeline to end before the timeout period.

Return Codes

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

Return Code: Meaning
8: A timeout occurred (message interval exceeded).
12: A GO command was entered.
16: A task executing a thread terminated.
32: An ABEND occurred on a task executing a thread.

Example: Causing a Wait with CORRWAIT

To display We will now wait 9 seconds. and wait for nine seconds, enter:

 PIPE CORRWAIT 9
      | LITERAL /We will now wait 9 seconds./
      | CONSOLE

Example: Using CORRWAIT to Wait for Messages

To issue the NetView LIST STATUS=OPS command for a logical unit (LU) named A157C9 in a remote domain, allow 60 seconds for each resulting asynchronous message to return to the pipeline and display the results, enter:

 PIPE NETVIEW RMTCMD LU=A157C9,LIST STATUS=OPS
      | CORRWAIT 60
      | CONSOLE

Example: Terminating a CORRWAIT

An important consideration in using CORRWAIT with non-NetView commands, such as VTAM and MVS commands, is proper termination of the wait. Allowing a timeout to occur can result in lost messages. Instead, explicitly end the CORRWAIT with a following TOSTRING, TAKE FIRST, or GO command.

When the last expected message can be detected by a simple comparison or count, use TOSTRING or TAKE FIRST after the CORRWAIT stage. When more complicated conditions apply, use the GO command.

In this example, we expect two VTAM ACTIVE messages. We terminate immediately on receipt of IST061I VARY ACT...FAILED message, but if good responses are received, we must count them.

Note: Certain VTAM message IDs are release dependent.

 PIPE VTAM V NET,ACT,SCOPE=ALL,ID=NTFELN7E
    | CORRWAIT 100
    | TOSTRING 1.7 /IST061I/
    | SAFE VTAMRESP
    | LOCATE 1.7 /IST093I/
    | DROP 1
    | PIPEND 0

The desired termination condition is stop as soon as you receive IST061 (failure message) or when you receive the second IST093. Notice that the first VTAM ACTIVE message is dropped after being stored in a name SAFE for later examination. The second VTAM ACTIVE message that is received drives PIPEEND 0, which causes the pipeline to end with a 0 return code.

Still more complex termination decisions can require you to drive a command procedure from a NETVIEW stage following your CORRWAIT. This procedure can examine the incoming messages one at a time and can create a named SAFE, if necessary. Like the DROP stage in this example, your procedure can produce a message to drive PIPEND when it is appropriate to end the wait.

Example: Early timeout following an expected message flow

This pipe waits three seconds for responses to begin and one second following any (unexpected) single-line message(s). Following receipt of an MLWTO (the expected IEE114I), it times out immediately.

 PIPE MVS D A,L | WAIT 3 10 0 | CONS

Example: Using a Secondary Output Stream with CORRWAIT

CORRWAIT can be coded to end when one of the following situations occurs:

60 seconds has elapsed.
The operator entered the GO command.
A task end or ABENDS.

For CORRWAIT to process in this manner, include the following statements in your pipeline specification:

...
|A: CORRWAIT 60
...
%
A:
|NLOCATE 1.11 /+0000000000/
|TAKE 1
|HOLE
...

Assuming that the pipeline end character was defined as a %, the simple pipeline after the A: connector processes the secondary output stream from CORRWAIT 60. If a completion code other than +0000000000 is processed, CORRWAIT terminates.