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

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. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. 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. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

1. The intended use of mvspause is for a program to wait on user ECBs plus signals.
2. 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.
3. 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.
4. 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

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

Characteristics and restrictions

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