NOTE - the argument retrieved by DitsGetArgument() will be an SdsCopy(3) of the original argument structure. As a result, you should not use DitsUfaceWait(3) to handle messages expecting replies with large argument structures.
In order to associate messages with this context, you must call DitsUfaceWaitInit() before calling the message sending routines (DitsGetPath(), DitsObey() etc.) DitsUfaceWaitInit() replaces a call to DitsUfaceCtxEnable() and you can revert to that style by calling DitsUfaceCtxEnable(). When you have finished processing messages, you should call DitsUfaceWaitComp(). You can have mulitple calls to DitsUfaceWait() between DitsUfaceWaitInit() and DitsUfaceWaitComp().
If the transaction id argument is non-zero, then will only return if that transaction completes.
The outstanding messages can be processed by calling this routine repeatly. The call will block if the last call. returned a count of 0, except if the DONT_BLOCK flag is set.
Note that if DitsUfaceWait/DitsUfaceTransIdWait/DitstActionWait/ DitsActionTransIdWait are called by other actions or events invoked whilst this call is active, the second action/UFACE context must be unblocked and end/reschedule before control will return to the first call.
If messages received while the context was blocked have not been processed when the DitsUfaceWaitComp is invoked, they are lost (a message is output using ErsOut). To ensure these messages are handled, you should continue calling this routine until count is returned as 0.
You can freely mix calls to DitsUfaceWait() and DitsUfaceTransIdWait().
| > | flags | int | A bit mask of flags. The possibilities are any
or-ed combination of-
|
|---|---|---|---|
| DITS_M_AW_FORGET | Forget any remaining messages from previous calls to this routine for the the info block. |
|---|---|
| DITS_M_AW_DONT_BLOCK |
Always return immediately. We
will only read a message if there was one outstanding
from a previous call.
If there are no outstanding messages or DITS_M_FORGET flag has been set, then no message will be read and count will be set to -1. Action |
| details | such as DitsGetArgument() etc. | will then
be as per prior to the call.
| |
| DITS_M_AW_NO_LIST |
Don't take an entry from the list. If
combined with DONT_BLOCK we simply get the
count of outstanding messages. Otherwise we block
waiting for a message. When the call returns, it
will be as per the first item on the list. It is not
clear if this flag is usefull to users without the
DONT_BLOCK flag.
|
|---|---|
| > | timeout | DitsDeltaTimeType * | If non-zero, the address of a reschedule delay. |
|---|---|---|---|
| > | info | DitsUfaceWaitInfoType * | A variable initialised by calling DitsUfaceWaitInit prior to a sequence of calls to this routine. It is used to maintain details about this context. |
| > | transId | DitsTransIdType | IF non-zero, the ID of a transaction to wait for. This must be a transaction ID of a message sent (or to be delivered to) this action. |
| < | count | int * | Set to the number of messages remaining to be processed. The message which caused the routine to be unblocked is not included. If the DITS_M_DONT_BLOCK flag was set, then count will be -1 if no messages were available. Count is always no-negative in other cases. |
| ! | status | StatusType * | Modified status.
WARNING - status of message receiving
code, not message status. To get the status of the received message,
fetch the value from DitsGetEntStatus().
|
| ImpReadEnd | Imp | Indicate completion of a read by pointer |
|---|---|---|
| SdsDelete | Sds | Delete a structure |
| SdsFreeId | Sds | Free a id |
| DitsMsgReceive | Dits | Received a dits message. |
| DitsUfaceTimer | Dits | Create a UFACE context timer. |
| DitsUfaceTimerCancel | Dits |
Cancel a UFACE context timer.
|
Click here for the DRAMA home page and here for the AAO home page.
For more information, contact tony.farrell@mq.edu.au