Museum

MBX_$COND_GET_REC_CHAN_SET        Domain/OS         MBX_$COND_GET_REC_CHAN_SET


NAME
     mbx_$cond_get_rec_chan_set - read a set of channels without waiting

SYNOPSIS (C)
     #include <apollo/base.h>
     #include <apollo/mbx.h>

     void mbx_$get_rec_chan_set(
          void *&mbx_handle,
          mbx_$chan_set_t &channel_set,
          void *&buffer_pointer,
          long &buffer_length,
          void **return_pointer,
          long *return_length,
          status_$t *status)

SYNOPSIS (Pascal)
     %include '/sys/ins/base.ins.pas';
     %include '/sys/ins/mbx.ins.pas';

     procedure mbx_$cond_get_rec_chan_set(
          in mbx_handle: univ_ptr;
          in channel_set: mbx_$chan_set_t;
          in buffer_pointer: univ_ptr;
          in buffer_length: integer32;
          out return_pointer: univ_ptr;
          out return_length: integer32;
          out status: status_$t);

SYNOPSIS (FORTRAN)
     %include '/sys/ins/base.ins.ftn'
     %include '/sys/ins/mbx.ins.ftn'

           integer*4 mbx_handle, channel_set(8)
           integer*4 buffer_length, return_length, status

           integer*4 buffer_pointer, return_pointer
           character buffer*32766, ret_buffer*32766

           pointer /buffer_pointer/ buffer
           pointer /return_pointer/ ret_buffer

           call mbx_$cond_get_rec_chan_set(mbx_handle, channel_set,
          &                                buffer_pointer, buffer_length,
          &                                return_pointer, return_length, status)

DESCRIPTION
     Mbx_$cond_get_rec_chan_set retrieves a client message from one of the
     channels specified by channel_set of the mailbox specified by mbx_handle.
     If there is no message available, mbx_$cond_get_rec_chan_set returns
     immediately with the status mbx_$channel_empty.

     mbx_handle
          The mailbox handle.

     channel_set
          A set of channels to check for messages.  The channel_set argument
          is a large set type.

     buffer_pointer
          A pointer to the data buffer allocated to receive the message.
          Mbx_$cond_get_rec_chan_set does not always use the buffer at
          buffer_pointer, but the caller must provide one.

     buffer_length
          The number of bytes available in the buffer that buffer_pointer
          points to.  Mbx_$cond_get_rec_chan_set will not write more than
          buffer_length bytes at buffer_pointer, and cannot write more than
          mbx_$rec_data_max.

     buffer_length
          The number of bytes that buffer_pointer points to.
          Mbx_$cond_get_rec_chan_set will not write more than buffer_length
          bytes at buffer_pointer, and cannot write more than
          mbx_$rec_data_max.

     return_pointer
          A pointer to the requested message.  Use this pointer to reference
          the message.  It is not necessarily equivalent to buffer_pointer.

     return_length
          If return_length is positive, it is the number of bytes in the mes-
          sage supplied at return_pointer, and no part of the message remains
          in the channel.  If return_length is negative, its absolute value is
          the number of bytes from the supplied message remaining in the chan-
          nel, and return_pointer points to only buffer_length bytes of the
          requested message.

          Mbx_$cond_get_rec_chan_set supplies the 6-byte server header each
          time it gets a portion of a message, so a server can always look at
          the cnt field to find out the total length of a message.

     status
          The completion status.  A status of mbx_$channel_empty indicates
          there is no message in the channel.

NOTES
     Only a server can use mbx_$cond_get_rec_chan_set.  Clients must use
     mbx_$get_conditional to conditionally get server messages.