SAS/C Library Reference, Vol. 1

ecbsuspend -- Suspend Execution Until a Signal or Post

SYNOPSIS

 #include <lcsignal.h>

 int ecbsuspend(sigset_t *mask, size_t listsize,
 struct _ecblist *ecblist);

DESCRIPTION

ecbsuspend delays program execution until it receives a C signal or until an Event Control Block (ECB) is posted. mask specifies the set of signals to be blocked while execution is delayed. listsize specifies the number of _ecblist structures addressed by the ecblist argument.

ecblist is the address of an array of structures, each of which represents one or more contiguous ECBs. Each structure contains two members: a count of the number of ECBs and the address of an array of ECBs. The count may be zero, in which case the ECB array address is ignored.

The declaration for the _ecblist structure is

 struct _ecblist {
    size_t count;
    unsigned *ecbarr;
 }

The ECB list for ecbsuspend is passed by the _ecblist structure for several reasons. It enables a static ECB list to be used in many cases because individual ECBs can easily be removed by setting their count member to 0. For applications that have a large number of ECBs, the _ecblist structure facilitates organizing them into arrays; this method may slightly improve the performance of ecbsuspend because fewer memory accesses are required to determine the addresses of all the ECBs.

ecbsuspend returns to its caller when one of the following events occurs:

an unblocked signal occurs. A handler for the signal is called after the signal mask is restored but before control returns to the caller from ecbsuspend.
an ECB is POSTed.

Several conditions for completion of the ecbsuspend function may occur simultaneously or nearly simultaneously. In such cases, a signal handler may be called even though an ECB was POSTed before or during arrival of the signal. On return from ecbsuspend, any number of ECBs may be POSTed, and more than one signal handler may have been called if the signal mask permits it.

RETURN VALUE

ecbsuspend returns - 1 if it was terminated due to receipt of a signal or due to an error. (errno is set to EINTR if the cause was a signal.) ecbsuspend returns 0 if it returned because an ECB was posted.

CAUTIONS

ecbsuspend does not clear any ECBs addressed by the ecblist argument. It is the caller's responsibility to clear the ECBs after a POST and to initialize them to zero or to some other suitable value.

The value returned by ecbsuspend may not be completely reliable. An ECB may have been POSTed even though a signal was detected, and a signal may have been received after ecbsuspend was awakened by a POST but before return to the user program was completely effected.

IMPLEMENTATION

ecbsuspend builds a standard OS ECB list for the ECBs indicated by its arguments, in addition to an ECB used internally by signal handling, and issues the OS WAIT macro to wait for a single ECB to be POSTed. If OpenEdition is active, the OpenEdition mvspause system call is used in place of an OS WAIT.

EXAMPLE

Wait for an alarm signal or for a POST representing a reply from the MVS operator:

  #include <lcsignal.h>
  #include <ctype.h>

  /* flag for SIGALRM handle */
  static int toolate = 0;
  static void timesup(int signum);

  int confirm()
  {
     unsigned ECB = 0;
     struct _ecblist myECBs = {1, 0 } ;
     char reply;
     sigset_t nosigs;

      /* Set up ECB list for single ECB.  */
     myECBs.ecbarr = &ECB;

     /* Issue WTOR macro via assembler.  */
     /* subroutine (not shown)           */
     wtor("Reply U to confirm request.", &reply, &ECB);

     /*Catch SIGALRM signal.             */
     signal(SIGALRM, &timesup);
     /* Wait 2 minutes for reply.        */
     toolate = 0;
     alarm(120);
      /* Set no sigs blocked for suspend. */
     sigemptyset(&nosigs);
     ecbsuspend(&nosigs, 1, &myECBs);
     /* Cancel alarm.                    */
     alarm(0);
     /* Restore default alarm handling.  */
     signal(SIGALRM, SIG_DFL);
        /* If the ECB was posted,           */
        /* return whether OK given.         */
        if (ECB & 0x40000000)
          return toupper(reply) == 'U';
        /* If we ran out of time,           */
        /* call asm to delete reply.       */
        else if(toolate){
           dom();
           /* Tell caller not to do it.       */
           puts("No reply received, treated as permission denied. ");
           return 0;
        }
  }

  static void timesup(int signum) {
     toolate = 1;
     return;
  }

RELATED FUNCTIONS

ecbpause, sigpause, sigsuspend