Put a message into a message queue.
CS_RETCODE srv_putmsgq(msgqid, msgp, putflags)
SRV_OBJID msgqid; CS_VOID *msgp; CS_INT putflags;
The identifier for the message queue. If you want to reference the message queue by name, call srv_getobjid to look up the name and return the message queue ID.
A pointer to the message. The message data must be valid until it is received and processed.
The values for putflags can be OR’d together. Table 3-88 describes each value’s significance:
Value |
Description |
|---|---|
SRV_M_NOWAIT |
When this flag is set, the call to srv_putmsgq returns immediately after the message is placed in the message queue. |
SRV_M_WAIT |
When SRV_M_WAIT is set, srv_putmsgq does not return until either the message is read or the queue is deleted. |
SRV_M_URGENT |
If this flag is set, the message is put at the head of the list of messages in the message queue instead of at the end. If more than one urgent message is added to a given queue, the urgent messages will appear at the head of the queue in the order in which they were enqueued. |
Returns |
To indicate |
|---|---|
CS_SUCCEED |
The routine completed successfully. |
CS_FAIL |
The routine failed. |
#include <ospublic.h>
/*
** Local Prototype.
*/
CS_RETCODE ex_srv_putmsgq PROTOTYPE((
SRV_OBJID mqid,
CS_INT flags
));
/*
** EX_SRV_PUTMSGQ
**
** Example routine to put a message into a message queue.
**
** Arguments:
** msgqid Message queue identifier.
** putflags Special instructions for srv_putmsgq.
**
** Returns:
**
** CS_SUCCEED
** CS_FAIL
*/
CS_RETCODE ex_srv_putmsgq(mqid, flags)
SRV_OBJID mqid;
CS_INT flags;
{
CS_CHAR *msgp;
msgqp = srv_alloc(20);
strcpy(msgp, “Hi there”);
return(srv_putmsgq(mqid, msgp, flags));
}
srv_putmsgq puts the message in *msgp into the message queue msgqid.
A message is always passed as a pointer. The data the message points to must remain valid even if the thread sending the message changes context.
In particular, be cautious when passing a message that points to a stack address in the context of the thread that sends the message. If you do this, you must guarantee that the thread that sends the message does not return from the frame in which it sent the message until the message has been removed from the queue. Otherwise, the message may point to a stack that is being used for other purposes.
The SRV_S_NUMMSGQUEUES server property determines the number of message queues available to an Open Server application. Refer to “Server properties”.
The SRV_S_MSGPOOL server property determines the number of messages available to an Open Server application at runtime. Refer to “Server properties”.
