amarquee.library/GetNextQMessage           amarquee.library/GetNextQMessage

   NAME
    GetNextQMessage - Wait for next QMessage to be received from the TCP thread.

   SYNOPSIS
    GetNextQMessage(session, timeout, signals)

   FUNCTION
    This function is available from ARexx scripts only.
    It replaces most of the functionality of the C Wait() call,
    and allows your ARexx script to sleep until a QMessage is
    ready, or an (optional) timeout occurs, or an (optional) signal 
    is raised.

   INPUTS
    session - The session pointer string that was returned by
              QNewSession (or a related function) to
              create this session.
    timeout - The number of milliseconds to wait before timing out
              and returning.  Set to zero to just poll for QMessages.  
              If this argument is set to less than zero, or is not 
              specified, then no timeout will occur (i.e. the function 
              will not return until a QMessage is available, or a signal 
              is raised).
    signals - A string specifying which interrupt signals should cause
              this function to return immediately.  If not specified,
              any interrupt signal will cause this function to return.
              (That is, this argument defaults to the value:
              'SIGBREAKF_CTRL_C|SIGBREAKF_CTRL_D|SIGBREAKF_CTRL_E|SIGBREAKF_CTRL_F')

   RESULTS
    Returns a pointer string to the QMessage if one became available,
    or zero if it had to return for some other reason (a signal was
    raised or the timeout period expired).  Note that signals CTRL-C,
    CTRL-D, CTRL-E, and CTRL-F will all cause this function to return,
    and also the signals will be propogated to the ARexx script (so
    it should be prepared to handle them!)

   NOTE
    It is an error to call GetNextQMessage() on a detached QSession.

   AREXX EXAMPLE
    /* Will return a QMessage is received, or when 5 seconds elapses, 
       or any CTRL-(C,D,E,F) combo is pressed. */
    message = GetNextQMessage(session, 5000) 
    if (message = 0) then say "Oops, timed out or signalled!" 
    else do
      say "Got QMessage with id " || GetQMessageField(message, 'ID')
      /* ... */
      call FreeQMessage(session, message)  /* must do this, or memory leaks */
    end

   AREXX EXAMPLE TWO
    /* Will return when a QMessage is received, or when CTRL-C or 
       CTRL-D are pressed */
    message = GetNextQMessage(session, -1, 'SIGBREAKF_CTRL_C|SIGBREAKF_CTRL_D')  
    if (message = 0) then say "Oops, timed out or signalled!" 
    else do
      say "Got QMessage with id " || GetQMessageField(message, 'ID')
      /* ... */
      call FreeQMessage(session, message)  /* must do this, or memory leaks */
    end
   
   SEE ALSO
    GetQMessageField