PIPE PPI

Syntax

PPI Sender
Read syntax diagramSkip visual syntax diagramPPI(DATAONLY) (TECROUTE) (TECRTCFM) (TRAPROUT) (MLWTO) (NV) receiver_name*
PPI Receiver
Read syntax diagramSkip visual syntax diagramPPI(APONLY) receiver_name
PPI Requestor
Read syntax diagramSkip visual syntax diagramPPI(APONLY) receiver_name /string/

Command Description

The program-to-program interface (PPI) stage communicates with another address space in the same host using the NetView® program-to-program interface. PPI can be used in three ways:
  • Sender
  • Receiver
  • Requestor

When PPI has an input stream, PPI acts as a sender. The data received on the input stream is passed to the receiver specified by receiver_name.

If PPI does not have an input stream, PPI acts as a receiver. The receiver_name specifies the name where data must be sent to be processed by the PPI stage.

When acting as a receiver, follow the PPI with CORRWAIT * so data can be received continuously without deactivating the receiver. If the receiver is deactivated, even for a short time, senders might encounter errors.
Note: When PPI is used as a receiver, the pipe option LOWQENAB is in effect even if not explicitly specified. See PIPE (NCCF) for more information about LOWQENAB.See HELP PIPE for more information in LOWQENAB.

When a /string/ is specified, PPI acts as a requestor. The /string/ is sent to the receiver specified by receiver_name and PPI waits for a response. A receiver name is automatically generated to receive the response.

When acting as a requestor, follow the PPI with CORRWAIT with a sufficient wait time for the response to be returned. PPI automatically ends the wait when one message is received. This message can be a multiline message.

The PPI stage, unlike other NetView PPI receivers, can receive multiline messages. Multiline messages must be in a specific format to be recognized by the NetView program:
  • The message must be prefixed with a seven character multiline identifier and a one-character line descriptor. The multiline identifier must be X'0F0DC4E2C9FFE3'. The line descriptor indicates the line type desired along with whether line attributes are provided.
  • Line type must be one of the following types:
    C
    Control line
    L
    Label line
    D
    Data line
    E
    End line (can contain data)
    Note: The first line must be a control line.

Streams

Stream Type Number Supported
Input 1
Output 2

Termination Conditions

PPI terminates when the input stream disconnects or if the secondary output stream disconnects, if defined.

An input stream can only be specified when PPI is used as a sender. Input messages are copied to the primary output stream if the primary stream is connected.

When PPI is used as a receiver or requestor, received messages are written to the output stream. These messages are identified by a sender message attribute if a sender name is provided. This sender name is the sender field IFRAUSDR.

A signed 10-digit decimal return code is written to the secondary output stream if the secondary stream is connected.

Operand Descriptions

receiver_name
A one-to-eight character name of the PPI receiver.

When PPI is a sender or requestor, receiver_name is the name of the program receiving the sent messages. The abbreviation *ALERT means the alert receiver name defined to the NetView program.

When PPI is a receiver, receiver_name is the name that is used by other programs to communicate with the PPI stage.

When PPI is used as a sender, receiver_name can also be an asterisk (*). Asterisk indicates that the message is to be returned to the program originating the message. The originating message is identified by the sender message attribute (IFRAUSDR).

APONLY
Specifies that messages are accepted only from an APF authorized program.
DATAONLY
Specifies that only the data portion of each line is sent. NetView buffer headers and structures are not sent. DATAONLY is only valid when PPI is used as a sender.
MLWTO
Specifies that the message receiver can receive messages formatted to NetView multiline message standards. Messages are sent as a NetView multiline message unit. MLWTO is only valid when PPI is used as a sender.
NV
Specifies that the receiver is another NetView. Multiline messages and attributes are sent to the receiver who reconstructs them into a multiline message.
TECROUTE
Specifies that the message or alert is to be formatted and transferred to the Event/Automation Service associated with the named PPI receiver. The message is converted by the Event/Automation Service into an Event Integration Facility (EIF) event and sent to the server.
TECRTCFM
Specifies that the message or alert is to be formatted and transferred to the Event/Automation Service associated with the named PPI receiver. The message or alert is converted by the Event/Automation Service into an an Event Integration Facility (EIF) event and sent to a server. The Event/Automation Service expects the server to send a reply confirming or rejecting the EIF event.
TRAPROUT
Specifies that the alert is to be formatted and transferred to the Event/Automation Service associated with the named PPI receiver. The alert is converted by the Event/Automation Service into a trap and sent to the SNMP manager. Note that text messages are not supported by TRAPROUT.
/string/
A delimited character string to be sent to the receiver specified by receiver_name.

Usage Notes

  • It is imperative, when passing an alert to the alert adapters, to send the entire original alert. Additions to the alert can be made using the NAMEBIND EDIT order. Deletions or other changes to the alert can cause the message to be unrecognized as an alert by the alert adapters.
  • When sending messages to another NetView system, the NV option preserves all message attributes except the cross domain sender name.
  • When PPI is used as a requestor, two return codes can be output to the secondary output stream: the first results from sending the request, the second from receiving the response. When the send fails, the receive is canceled and only the return code from the send is passed to the secondary output. When the receiving session cannot be established, only the receive initialization failure code is returned. See the IBM® Tivoli® NetView for z/OS® Application Programmer's Guide for more information about PPI return codes.
  • The PPI stage is not supported under the PPT task.
  • When PPI is used as a requestor, the PPI stage chooses a receiver name that is used to receive a reply. The name chosen is in the form aa#xxxxx where aa is the system default defined by the PPIPREFX keyword on the DEFAULT command and xxxxx is a value dynamically chosen at run time. For more information about PPIPREFX, see HELP DEFAULT. For more information about PPIPREFX, see IBM Tivoli NetView for z/OS Command Reference Volume 1 (A-N).

    If an error is detected in the PPI prefix, a return code is passed to the secondary stream. If a secondary stream is not defined, message DWO411I is issued with the incorrect PPI prefix.

  • Access to PPI functions can be controlled using SAF or the NetView Security Table.

    Security checking is done for the pseudo-keywords RECEIVE and SEND on a DSIPIPPI command. The SEND pseudo-keyword controls both the sender and requestor functions of PPI.

    The SEND and RECEIVE pseudo-keywords correspond to the PPI receiver_name specified on the PPI stage.

    To prohibit using: 
    PIPE PPI GEORGE | WAIT ...
    Code the following PROTECT statement: 
    PROTECT *.*.DSIPIPPI.RECEIVE.GEORGE
    To prohibit using: 
    PIPE LITERAL /STUFF/ | PPI SAM ...
    Code the following PROTECT statement: 
    PROTECT *.*.DSIPIPPI.SEND.SAM

Return Codes

The following return codes are returned by the PPI stage as signed, 10-digit decimal numbers:
Return Code
Meaning
0
PPI completed successfully.
100
A system abend occurred during a PPI service send or receive. This might be a forced closure of the PPI address space.
104
A user abend occurred during a PPI service send or receive. See the IBM Tivoli NetView for z/OS Application Programmer's Guide for more information about user abends.
1001
The AIFR or the input length was not valid.
1002
Did not identify the data as a message or MSU.
1003
An incomplete multiline message was discarded by the PPI stage because of the receipt of an unrelated message from the same sender.
1004
An illegal alert forwarding loop was detected. The NetView program attempts to avoid loops by not forwarding alerts back to their source. Specifically, PPI (TECROUTE) or PPI (TECRTCFM) is not valid for a generic alert whose subvector X'92', flag bit 7, is on ('1' B). PPI (TRAPROUT) is not valid for a generic alert whose subvector X'92' flag bit 4 is on. For more information, refer to the SNA library.
1005
The specified target type does not support the data. For example, (TRAPROUT) was specified for a message which is not an alert.
1012
The user is not authorized.
Other
Any valid return code returned by a PPI request type 4 (init), 14 (send), or 22 (receive). See the IBM Tivoli NetView for z/OS Application Programmer's Guide for information about these return codes.

Example: Generating an Alert from Hex Data

The following REXX example produces an alert similar to the following example on the NPDA ALD screen: 
   NTV7E GENAL3   COMC 13:43 EQUIPMENT
                  MALFUNCTION:COMM SUBSYST CTRL

The text 'Here is my subvector 31 stuff.' is seen by selecting the alert and entering "D" to view the event detail.

Note: Vector lengths in alerts must be correct or the alert might not be recognized. 
/*** Make an alert  ********/
altxt =        '41038D000000000000780000'X
altxt = altxt||'0B92000001100012345678'X
altxt = altxt||'1010000D110E0A0040F2F3F4F5F6F7F8'X
altxt = altxt||'069304032012'X
altxt = altxt||'0E950601150213E1068101011504'X
altxt = altxt||'1103030109C7C5D5C1D3F34040C3D6D4C3'X
altxt = altxt||'04931001'X
altxt = altxt||'30310602046E01F40512'X||'ENU'||'032111'X
altxt = altxt||'2030'X||'Here is my subvector 31 stuff.'
'pipe (end =) var altxt',
'| a: PPI *ALERT',
'|cons dump',
'= a:',
'|color whi',
'|cons'

Example: Responding to Requests

The following simple example responds to the COUNT request with the number of requests processed so far. Other requests receive the response ERROR 1.
Note: The receiver is not shut down when the pipeline ends so the response can be generated.
/*** responding to a request ********/
'PIPE (NAME CNMCOUNT END ¬)',
'| PPI CNMCOUNT',     /* receive for receiver name "CNMCOUNT" */
'| WAIT *',           /* CORRWAIT (until RESET or STOP FORCE) */
'| COUNT EACHLINE',   /* using line count for requested data  */
'| X: LOC 1.5 /COUNT/', /* valid requests...                  */
'| EDIT LINECOUNT 1', /* constructing the simple response     */
'| PPI *',            /* sending the response to requestor    */
 ,       /* -------------------- end of pipeline 1 ---------- */
'¬ X:',               /* invalid requests come here.      */
'| EDIT /ERROR 1/ 1', /* error message...                     */
'| PPI *'             /* sending error message to requestor   */
Note:
  1. The first stage, PPI CNMCOUNT, records the sender's ID as a message attribute in each message. The attribute is used by the sixth stage, PPI *, to send the response back to the originator.
  2. The EDIT stage in this example can be written with the WRITELINE order to create a multiline message. Because this example does not assume that the requestor is another NetView system, it cannot assume that the requestor can handle a multiline response.

    Adding the NV option to the PPI send stage, stage 6, adds the appropriate multiline identifiers to the data before it is sent to the requestor.

Example: Receiving a Response

In this example a request is sent to a remote PPI receiver running in another address space. The pipeline then waits for a response.

This example assumes that the remote receiver is another NetView system. Because it is another NetView system, a multiline response is possible. 
/*** issuing a request ********/
address NETVASIS,
'PIPE  (NAME PPIOPS)',
'| PPI OEXXX /egrep "NetView" set.log/', /*sendrequest 'egrep'*/
'| WAIT 180',                        /*wait to 3 min for resp */
| STEM NVnSET.'                      /*store response         */
Note:
  1. The wait automatically ends when one message is received. This message can be a multiline message.
  2. Multiline identifiers and line descriptors, if any, are removed when the multiline response is built by PPI processing.

Additional Examples

For additional PPI examples, see the following specifications:
  • HELP PIPE EDIT
  • PIPE EDIT
  • Example CNMEALUS in DSICLD
  • Example CNMEMSUS in DSICLD
  • Sample CNMS1101