mvspauseinit (BPX1MPI, BPX4MPI) — Set up to wait on user events plus signals

Function

The mvspauseinit callable service allows the thread to declare to the system a list of event control blocks (ECBs) the application program will use to receive event notifications. This service is used in conjunction with the mvspause service.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task - No EUT FRRs
Cross memory mode:	PASN = HASN
AMODE (BPX1MPI):	31-bit
AMODE (BPX4MPI):	64-bit
ASC mode:	Primary address space control (ASC) mode
Interrupt status:	Enabled for interrupts
Locks:	Unlocked
Control parameters:	All parameters must be addressable by the caller and in the primary address space.

Format

CALL BPX1MPI,( Addr_of_ECBlist,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4MPI with the same parameters. The Addr_of_ECBlist parameter is a doubleword.

Parameters

Addr_of_ECBlist

Address of a list of up to 1018 user-defined event control blocks (ECBs). The system uses the first ECB in the list.

Type:: Pointer
Length:: Fullword (doubleword)

The name of a fullword (doubleword) from which the service extracts the address of the input ECB list. The mvspauseinit service requires this list to contain a maximum of 1018 ECBs, with the first ECB dedicated to the system. The user is responsible for obtaining the storage for all ECBs.

All pointers in the ECB list are 32-bit pointers for both AMODE 31 and AMODE 64 callers, as ECBs are only supported below the 2 GB bar. The last ECB pointer in the list must have the high-order bit set to 1 (80000000x). This bit indicates that it is the last ECB address in the list.

Return_Value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the service returns a 0 upon normal completion, or -1 otherwise.

Return_Code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the mvspauseinit service stores the return code. The mvspauseinit service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The mvspauseinit service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EFAULT	Error addressing parameters. The following reason codes unique to the mvspauseinit service can accompany the return code: JRECBError, JRECBListBad.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the service routine stores the reason code. The reason code further qualifies the return code value. The mvspauseinit service stores a reason code only when the return value is -1. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

The intended use of the mvspauseinit service is for a program to declare to the system a list of pointers to user ECBs in user-managed storage. These ECBs are used by the mvspause function to suspend the thread until a signal arrives or a user-defined event is posted.
The user is responsible for initializing all ECBs, including the signal ECB. The first ECB is the signal ECB. The system does not alter the ECBs during mvspauseinit. This means that an asynchronous operation may post an ECB in the ECB list while mvspauseinit is operating.
After mvspauseinit returns to the caller, the mvspause service may be invoked as many times as necessary without reinvoking the mvspauseinit service. If the application program needs to change one or more ECB addresses, the application must reinvoke the mvspauseinit service before invoking the mvspause service.
Note: Only one ECB list is allowed per thread. If a user invokes the mvspauseinit service multiple times, each invocation replaces the ECB list specified on previous invocations of mvspauseinit.

Related services

mvspause (BPX1MP, BPX4MP) — Wait on user events plus signals

Characteristics and restrictions

There are no restrictions on the use of the mvspauseinit service.

Examples

For an example using this callable service, see BPX1MPI (mvspauseinit) example.