The Inter-task Messaging library (CXMSG.DLL) provides the means to pass messages between Telecom Engine tasks.     Either the process ID of the task or the task name (if set by msg_setname() is called) can be used to identify a particular task to send a message to.

The sending side would then use the msg_send() function to send a string message to the recieving task.    The receiving task must use msg_read() to then retrieve the message.         All messages will be received in the order that they are send and they will be added sequentially to a queue if the receiving task is not already waiting for the message by a call to msg_read(). 

It is important that the receiving task retrives the incoming messages before the the incoming message queue gets full.    By default the maximum number of messages that can be in the incoming message queue for all tasks is  512 messages.     If this limit is reached then an error message is generated and the current message queue is dumped to the system tracelog,  however on this first occasion the message queue is automatically increased to hold 1536 messages and the msg_send() function will still complete sucecssfully.   

If however this new message queue limit is reached then all further calls to msg_send() will fail and an error message will be sent to the system error log.

Note that when a task is killed (either by a specific task_kill() function call, or implicitly after a stop or restart statement or a call to task_chain()) then all messages destined for that task that are waiting in the message queue will be deleted.

Note that is is possible that one task may attempt to send a message to another task using the task ID,  but the task that the message was destined for has recently been stopped and another task has started running using the same task ID.        In this situation an unexpected message may appear in the message queue for the newly started task.         Programmers should take care to handle this situation by calling msg_flush() prior to calling msg_send()/msg_read() for the first time to ensure that there are no stry messages in the tasks message queue.      This still could leave a small window of opportunity for a stray message to arrive after the call to msg_flush() and so other mechanisms may be taken (such as using a session number in the send/received messages) to cover this rare eventuality if it could cause problems/bugs to occur .

For example here is some code that requests a server task to return some kind of resource (E.g. an outbound channel)..         This code covers all the eventuallities mentioned above about stray messages and uses a session number of correlate sent and received messages and the programmer should implement similar mechanisms to ensure correct code for this kind of functionality.

       // Clear any stray messages in the message queue

       msg_flush();

       

         // Get a unique session ID

       session_id=get_unique_number();

       // Send a message to the resource handler to get the resource

       x=msg_send("resouce_task","GET," & session_id);

       if(x < 0)

               errlog("Failed to send message: err=",x);

               // Force jump to onsignal function to clear down call...

               task_hangup(task_getpid());

       endif

       // Now wait up to 10 seconds for response

       resp_str=msg_get(10);

       // resp should be in the form RSP,session_id,resource

       strtok("","");

       resp=strtok(resp_str,",");

       resp_sess=strtok(resp_str,",");

       resp_resource=strtok(resp_str,",");

       // Check that this message is a valid response to our request

       if(resp strneq "RSP" or resp_sess!=session_id)

               errlog("Got a bad message!  msg was ", resp_str);

               // Force jump to onsignal function to clear down call...

               task_hangup(task_getpid());

       endif

       ETC...