Define and Initialize a Receiver

To define or initialize a receiver, use request code 4. This request code lets you perform the following functions:

Define a receiver—it declares the name of the receiver and the buffer limit.
Initialize a receiver that does not exist.
Reactivate a defined but inactive receiver.
Alter the buffer queue limit. This function can be performed at any time, as long as all the fields are specified, and the TCB/ASCB addresses match those addresses of the defined receiver.
Changing the value of the buffer queue limit does not drop buffers if it is reduced. The change only prevents additional buffers from being queued.

Prevent the accidental overwrite of an existing receiver definition by setting REQIND1 to X'80'. This flag causes an exclusive-active check to be made, that is, if the receiver is presently active, no change is made to it, regardless of a match on the TCB/ASCB addresses.

The RPB fields in the following table must be set up before the call:

Bytes	Field Name	Set to...
00–03	RPLEN	56.
04–05	REQUEST	4.
06–07	RECOPT	A recovery option as required.
12–15	WORADDR	The address of a 128-byte work area.
16–19	ASCBADDR	The address of the current ASCB (can be obtained by a request type 3).
20–23	BUFFQL	The buffer queue limit: 0 to PPI maximum parameter.
24–31	RECVERID	The receiver ID.
32–33	AUTHIND	0 if senders do not require authorization or 1 if senders must be APF authorized.
36–39	TCBADDR	The address of the current TCB (can be obtained by a request type 3).
46	REQIND1	Bit 0 (X'80') if an exclusive-active check is wanted.

The RPB fields in the following table are returned after the call:

Bytes	Field Name	Set to...
08–11	RETCODE	The return code.
20–23	ECBADDR	The address of the receiver ECB.

The following return codes are possible:

0: Request completed successfully—ECB address is set.
16: The receiver program is already active, and the TCB/ASCB address did not match, or they matched but the exclusive-active check flag (REQUIND=X'80') is set.
22: The requestor is not in primary addressing mode.
24: PPI is not active.
25: The ASCB address is not correct.
28: PPI requests are not supported.
32: No storage is available.
36: ESTAE could not be established as requested.
40: Receiver ID is invalid.
90: A processing error occurred.

Notes:

Only this product can define receiver ID names starting with NETM or NETV, unless the PPINETM/R parameters are set to NO.
The returned ECB-address field provides the address of an ECB, in the TCB key of the caller, in a protected subpool (that is, cannot be freed by user code), that is posted when buffers are available to the receiver. Do not alter this ECB, which is automatically cleared and posted when relevant.
The return code is 0 if buffers are available, and 99 if the PPI facility is shutting down.
Tivoli NetView 2.4 lets you define a receiver passing a zero ASCB address—in this case, it does not allocate an ECB. The SOLVE PPI does not support this feature and returns RETCODE=25 (invalid ASCB address).