Retrieves a board message from the driver, if one is available.

DWORD agmGetAGMessage ( AGMHD agmhd,
AGM_AGMSG *msg)

agmhd Handle returned by agmOpen.

msg Pointer to an AGM_AGMSG structure to receive the board message from the driver. AGM_AGMSG is defined as:

typedef struct
{
     WORD  message ;
     WORD  channel ;
     WORD  object ;
     BYTE  stream ;
     BYTE  instance ;
     DWORD time ;
     WORD  reserved ;
     BYTE  bufcnt ;
     BYTE  parmcnt ;
     WORD  parms[16]; 
} AGM_AGMSG ;

• SUCCESS
• AGMERR_BAD_ARG
  One of the arguments is invalid.
• AGMERR_FAILURE
• AGMERR_QUEUE_EMPTY
  A valid AG message was not available.
• AGMERR_SIGNALLED
  An artificial message (sent via agmSignalMuxHandle) was received.

This function retrieves a board message from the driver. If there is none available, it returns AGMERR_QUEUE_EMPTY. The state of the mux handle returned by agmOpenDriver indicates whether or not the queue is empty. Normally, an application will wait on that mux handle before calling agmGetAGMessage.

agmGetAGMessage returns AGMERR_QUEUE_EMPTY which indicates that no message was found in the queue.

agmGetAGMessage returns AGMERR_SIGNALLED if, instead of a driver message, an artificial message sent via agmSignalMuxHandle was retrieved. In this case, msg->parms(0) and msg->parms[1] contain the code and board fields, respectively.

The msg argument is a pointer to an AG message structure that will contain the message sent up from the board. The fields of AGM_AGMSG are:

Field	Description
message	The message code, bit 15 = direction, bits 8-13 = category.
channel	The channel, high byte = board number.
object	Overlay or function ID code (if relevant).
stream	Stream number.
instance	Instance number.
time	Timestamp (10ms units).
reserved	Reserved. Must be zero (0).
bufcnt	Number of buffers.
parmcnt	Number of parameters.
parms	Array of parameter values.

agmFormatAGMessage, agmOpen, agmOpenDriver, agmSignalMuxHandle

for (;;)
{
  AGM_AGMSG agmsg;
    DWORD ret;

    /* Wait for muxhd to be signaled */
    if (wait_event (muxhd) != SUCCESS)
        break;

    ret = agmGetAGMessage (agmhd, &agmsg);
  if (ret == AGMERR_QUEUE_EMPTY)
   puts ("False alarm -- no message.");
  else if (ret == AGMERR_SIGNALLED)
  {
   printf ("muxhd was signaled via agmSignalMuxHandle: code=%d, board=%d\n",
    agmsg.parms[0], agmsg.parms[1]);
        break;
  }
  else if (ret == AGMERR_FAILURE)
  {
        puts ("agmGetAGMessage failed");
   break;
  }
    else
    {
        char tmpstr[256];
    
        agmFormatAGMessage (agmsg, tmpstr, sizeof tmpstr);
        printf (tmpstr);
    }
}