PIPE PERSIST

Syntax

PERSIST

Command Description

The PERSIST stage specifies the disposition for correlated output after a pipeline ends. Use PERSIST following a stage (for example, the NETVIEW stage) that creates correlated output. If used with a wait stage (CORRWAIT), the PERSIST stage should follow the wait stage. As long as the preceding stage is connected, the PERSIST stage is merely a pass-through for any messages. After the preceding stage disconnects, the disposition of correlated messages begins as specified in the arguments.

Streams

Stream Type	Number Supported
Input	1
Output	2

Termination Conditions

The operation (as pass-through) of the stage ends when the preceding stage disconnects. At this time, the action on correlated messages that is specified by the argument begins. The action continues until either: (a) the time specified expires or; (b) the correlation environment ends because the commands involved have all indicated an affirmative end. Note that MVS commands do not indicate an end, and commands that issue MVS commands also do not indicate an end.

Operand Descriptions

minutes: Specifies the number of minutes that the PERSIST condition is active following the completion of the pipeline in which it is found. The range is 0 - 100,000.
MINUTES: Optional parameter, used only for readability.
DISPLAY: Indicates that the correlated output is to be displayed on the console of the task where the pipeline ran. The output messages can be automated.
ROUTE: Indicates that the correlated output is to be sent to the specified task.
label:: Specifies a valid label that can be used by the ROUTE stage.
COMMAND: Indicates that the specified command is to be run under the task where the pipeline ran.
cmd: Specifies the command to be processed.
The command is invoked once for each message received by the PERSIST stage. When the command is invoked, the newly-received message becomes the current message and is available to the command through the use of pipe stage SAFE * or REXX functions such as MSGID.
TRAP: Specifies that messages are to be added to the message queue of the REXX procedure which called the pipeline containing the PERSIST TRAP stage. Such messages satisfy a REXX WAIT FOR MESSAGES command and are accessible to a MSGREAD command.
See the sample usage of PERSIST TRAP under option 13 in sample CNMS1101.
tText: Specifies optional text to be written to the message queue as a last message at the time the persist completes. Note that MVS™ commands and the VTAM® VARY command do not generally give an indication of completion. For these commands, the tText parameter is only written to the queue when the specified timeout occurs. After receiving the message containing this text, the procedure does not issue another WAIT FOR MESSAGES request or use the VIEW option EXTEND with respect to the completed persist.

Usage Notes

Issue NCCF LIST PERSIST to get information about outstanding PERSIST elements.
The PERSIST stage defines the action to be taken for messages that arrive after termination of the correlation represented by a CORRWAIT stage. The conditions defined by PERSIST are enabled following termination of the preceding CORRWAIT stage (WAIT) when one of the following statements is true:
- WAIT times out
- WAIT responds to GO or RESET
- WAIT end prematurely because of a PIPEND (non-zero return code)
- DEBUG option is in effect for the PERSIST stage
The PERSIST stage can be used after a NETV stage without any WAIT stage. In this case, the PERSIST stage is always enabled and absorbs all messages from the preceding command, even synchronous messages.
The command, routing, or display specified on your PERSIST stages is activated by the arrival of a message that was to be correlated to the CORRWAIT preceding your PERSIST, had that wait not ended prematurely.
Unless DEBUG is in effect, the PERSIST condition is disabled when an affirmative end of processing is detected by PERSIST. All native NetView® commands provide this affirmative end signal when complete. For VTAM in MVS release 10 and later, VTAM commands DISPLAY, MODIFY, and a few VARY commands also provide it. MVS commands and most VTAM VARY commands do not have an affirmative end.
If you specify more than one PERSIST stage for a given command correlation environment, only the last specified PERSIST stage takes effect.
Messages subject to DISPLAY action are exposed to user exits, trapping, automation, and logging just as for uncorrelated messages.
Messages subject to ROUTE action are routed first, then are exposed as for other messages.
A message subject to COMMAND action is provided as the current message when the indicated command runs. Any output from the command, including the original message, is subject to exposure in the same way as the output of a command issued from the command facility command line.
When PERSIST invokes a command, it does so with the same authority as was in effect for the pipeline which established the PERSIST action.
When PERSIST TRAP is active, the invoking procedure can issue a WAIT FOR MESSAGES command or use the EXTEND option on a VIEW command to wait for additional data. When the persist completes, the REXX function EVENT() returns a value of X.
Do not use the TRAP option when including the PERSIST stage in sample DSICCDEF.

Example: Issuing a VTAM Command

To issue the VTAM command V NET,ACT,ID=X displaying initial messages from the VARY command for 10 seconds and then routing any further messages for an additional 30 minutes, enter:

EXCMD oper1 PIPE CORRCMD 10 V NET,ACT,ID=X
   | PERSIST 30 MINUTES ROUTE AUTHRCVR
   | CONSOLE

The default action for CORRCMD VARY is PERSIST DISPLAY. In this example, the default action is overridden by the specified PERSIST stage. Only the specified PERSIST stage is activated.

Example: Continuing Work During an Asynchronous Request

To continue with other work while an asynchronous request completes, enter:

'PIPE CPDOMAIN USIBMNT.RMTCP',
   '| PERSIST 1 TRAP'
   /* other work here, including other pipe commands
      with their own waits or persists  */
   /* we've been "waiting" some already... see if any
      more waiting is needed...         */
   'WAIT 20 SECONDS FOR MESSAGES'  
   IF EVENT() = 'M' THEN
    do;
      'MSGREAD'
      /* act on msg from CPDOMAIN  */
    end;