mvspause (BPX1MP, BPX4MP) — Wait on user events plus signals
Function
The mvspause callable service allows a thread to suspend until a signal arrives or some application-defined event is posted.
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 (BPX1MP): | 31-bit |
AMODE (BPX4MP): | 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
The syntax format is as
follows:
CALL BPX1MP,( Return_value,
Return_code,
Reason_code)
AMODE 64 callers use BPX4MP.
Parameters
- Return_Value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the service returns a
0
indicating that an event occurred, or-1
otherwise. - Return_Code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the mvspause service stores the return code. The mvspause service returns Return_code only if Return_value is-1
. For a list of return code values, see Return codes (errnos) in z/OS UNIX System Services Messages and Codes. The mvspause service can return one of the following values in the Return_code parameter:Return_code Explanation EFAULT Error addressing parameters. The parameters on the prior mvspauseinit call were not fully validated at mvspauseinit time. The following reason code unique to the mvspause service can accompany the return code: JRECBStateBad. EINTR The mvspause call was interrupted by a signal. EMVSPARM Incorrect parameters were passed to an MVS™ service. The following reason codes unique to the mvspause service can accompany the return code: JRECBListNotSetup, JRECBStateBad. - 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 mvspause service stores a reason code only when the return value is
-1
. For a list of reason codes, see Reason codes in z/OS UNIX System Services Messages and Codes.
Usage notes
- The intended use of mvspause is for a program to wait on user ECBs plus signals.
- The user must first invoke the mvspauseinit service to declare to the system the list of ECB pointers to use. The system makes a copy of the list of ECB pointers to wait on and uses the existing MVS WAIT service to wait for the user events and the signal event.
- When one of the ECBs in the ECB list has been posted or a signal is received, the mvspause operation concludes and control is returned to the caller. When a signal is received, the mvspause service posts the signal ECB and runs the signal handler before returning to the user.
- The user has the option of reinvoking the mvspause service without
reinvoking the mvspauseinit service. The user should be aware, however,
that the system has made a copy of the list of pointers that point
to the user's ECBs. Any changes to the caller's copy of the ECB pointer
array are not reflected in the system copy unless the mvspauseinit
service is invoked again. Furthermore, when the user wishes to reinvoke
the mvspause without reinvoking the mvspauseinit service, the user
must clear all ECBs that were posted. This includes clearing the signal
ECB. If the user does not clear posted ECBs, the mvspause detects
the already posted ECB and returns immediately. The user must take
care when clearing ECBs, because not all ECBs may have been posted.
Asynchronous operations could post an ECB at any time during the user's
processing. The user should clear only ECBs that are processed, and
not blindly clear all ECBs. The following logic example displays one method for processing ECBs:
CALL MVSpauseInit(list of ECB addresses); for(;;) /* Do forever */ { call MVSpause() for(i=1;i<=MaxEcbs;i++) { Copy value of Ecb(i) if (Ecb(i) was posted) { Clear Ecb(i) switch(i) { case 1: CALL Signal-Occurred; break; case 2: CALL Rtn_for_2nd_Ecb; break; case 3: CALL Rtn_for_3rd_Ecb; break; ... /* As many as are needed */ default: no ECBs POSTed } /* end switch */ } /* end if */ } /* end for */ if (terminating condition occurred) break; /* Exit Do Forever loop */ } /* end do forever */
Related services
Characteristics and restrictions
There are no restrictions on the use of the mvspause service.