mesgrcv

Name

mesgrcv � Get an IPC message

Synopsis

#include <sys/types.h>
#include <sys/msg.h>
#include <sys/ipc.h>
#include "mesg.h"
#include "spp.h"

int mesgrcv (morig,msgp,msgsz,msgtyp,msgflag,msgrtime)
int morig
union msgunion *msgp; /* message buffer */
int msgtyp; /* type of message to read */
int msgsz; /* size of message buffer */
int msgflag; /* control flag */
long *msgrtime; /*message receive time */

Description

mesgrcv is used by the voice system to read IPC messages off their RM or message queues. mesgrcv reads the next IPC message on the message queue (morig) and stores up to msgsz bytes in the buffer pointed to by msgp. The buffer should be as large as the largest message to be read. Otherwise, by default, mesgrcv will discard the message if its size is greater than msgsz. However, if (MSG_NOERROR & msgflag) is true, the message will truncated to fit in the buffer.

mesgrcv can read messages of a certain type selectively as specified by msgtyp. Set msgtyp to zero to read the first message on the queue regardless of type.

By default mesgrcv waits indefinitely for a message to arrive on the queue if there is none currently to be read. However, if (msgflag & IPC_NOWAIT) is true, mesgrcv returns immediately with a -1 and errno is set to ENOMSG when no message is found on the queue. mesgrcv also returns (in msgrtime) the time the message was read and stored in the buffer (* msgp ) if IPC_GTIME & msgflag is true. The mesgrcv function creates the IPC message queue for queue key morig if necessary.

Example

The following are examples of code fragments using mesgrcv to receive IPC messages. The examples assume that a TSM script is sending two types of messages. One contains the caller's personal information and the second contains the caller's order for a specified number of widgets.

/* Definition of the message structures and definitions
* used in the examples below.
*/
#include <sys/errno.h>
#include <sys/types.h>
#include <sys/ipc.h>
#include <stdio.h>
#include "spp.h"
#include "mesg.h"

typedef enum {VISA,AMEX} CREDIT_CARD_TYPE;

/* Define messages to receive */
struct callerinfoMsg {
struct mbhdr hd; /* see mesg.h */
CREDIT_CARD_TYPE creditCard; /*VISA, AMEX */
int creditCardNo; /* employee number */
};
#define CALLER_INFO 6910 /* message id */

struct orderMsg {
struct mbhdr hd; /* see mesg.h */
int noWidgetsOrdered; /* employee number */
};

#define ORDER_AMOUNT 6930 /* message id */

/* Actual area for receiving messages.
* Compose of all expected messages.
*/
union msgBuffer {
struct orderMsg order;
struct callerinfoMsg caller;
} MsgRcvArea;

union msgBuffer *Msgp = &MsgRcvArea;

extern int errno;

char *Myname = "WidgetDip";
int myQkey; /* my very own message queue */
int noBytesRead;
long Msgrtime;

/* Dummy function that contains the examples.

void
receiveExamples()
{
/*******Example I
* To read the first message on the queue and find out
* what message you got:
*/
int howMany;
CREDIT_CARD_TYPE cardType;
int cardNo;

noBytesRead = mesgrcv(MyQkey,Msgp,sizeof(union msgBuffer),
0,0,NULL);
if (noBytesRead > 0) { /* no error */
/* Time to unpackage the message and find out
* what message arrived.
*/
switch (Msgp->order.hd.mcont) {
case ORDER_AMOUNT:
howMany=Msgp->order.noWidgetsOrdered;
/* Process order */
break;
case CALLER_INFO:
cardType=Msgp->caller.creditCard;
cardNo=Msgp->caller.creditCardNo;
break;
default:
/* Unknown message received.
* Notify someone and probably go back
* and read something else.
*/
;/* null statement to make code compile for this example */
}
} else {
/* Could not read message for some reason.
* Depending on the error, might want to re-try reading.
* Check errno if noBytesRead==-1.
*/
}

/*******Example II
* To read message without waiting if there's none now.
* And to get the time the message was read:
*/
noBytesRead= mesgrcv(MyQkey,Msgp,sizeof(union msgBuffer),0,
IPC_NOWAIT, &Msgrtime);
if (noBytesRead == -1 && errno == ENOMSG) {
/* No message is on the message queue.
* Do some other work and then come back and re-read queue
*/
} else if (nobytesRead > 0) {
db_pr("%s: got message on %ld\n, MyName, Msgrtime);
/* process message */
} else {
/* some other error occurred */
; /* null statement to make code compile */
}
}

Diagnostics

Upon successful completion, mesgrcv returns the number of bytes read, ranging from 1 to msgsz. Otherwise, one of the following negative values is returned:

� 2002 Avaya Inc. All Rights Reserved.