The outstanding messages can be processed by calling this routine repeatly. The action (not the task) will block if the last call returned a count of 0, except if the DONT_BLOCK flag is set.
Note that if after this call is invoke, another action is invoked and calls DitsActionWait/DitsActionTransIdWait/DitsUfaceWait/DitsUfaceTransIdWait, then second action must be unblocked and end/reschedule before control will return to the first action.
If messages received while the action was blocked have not been processed when the action completes, they are lost (a message is output to stderr). To ensure these messages are handled, you should continue calling this routine until count is returned as 0 or reschedule and handle them in the normal reschedule event process.
The action is NOT unblocked when a KICK is received for the action which invokes it, but the Kick handler will be invoked may cause the action to be rescheduled and the action will then be unblocked when the reschedule occurs. An except to this is if the KICK handler causes the action to end. In that case, this routine will return with either the status of the KICK handler (if not STATUS__OK) or with the a STATUS of DITS__WAIT_ABORTED.
If the transaction id argument is non-zero, then will only return if that transaction completes.
This routine may be invoked from either Obey or Kick context of an action, but not both at the same time (status = DITS__WAITALRDY will be returned). If invoked from a Kick handler, the obey handler may stage. If the obey handler causes the action to end, then this routine will return with either the status of the Obey handler (if not STATUS__OK) or with the a STATUS of DITS__WAIT_ABORTED.
If an action which has invoked this routine is killed using DitsKillByName(3)/DitsKillByIndex(3), then this routine will return with a status of DITS__WAIT_ACT_KILLED or the status supplied to the kill routine. The caller should return immediately - whist it could ignore this bad status and cause an allow the action to continue - this is considered rude as the kill routines should cause the action to die.
If after doing a call to DitsActionWait() which returned with count>0, you then reschedule your action (using DitsPutRequest()) with a request of DITS_REQ_STAGE, DITS_REQ_WAIT, DITS_REQ_MESSAGE or DITS_REQ_SLEEP, then DRAMA will commence processing your list of outstanding transactions, as normal reschedule events - i.e. your obey handler is invoked for each message on the list.
|>||flags||int||A bit mask of flags. The possiblities are any
or-ed combination of-
|DITS_M_AW_FORGET||Forget any remaining messages from previous calls to this routine for this action.|
Always return immediatley. 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.
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
|>||timeout||DitsDeltaTimeType *||If non-zero, the address of a reschedule delay.|
|>||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 non-negative in other cases.|
|!||status||StatusType *||Modified status.
WARNING - status of message receiving
code, not the message status. To get the status of the received message,
fetch the value from DitsGetEntStatus(). Also - a timeout does not
set the status bad, it sets DitsGetEntReason() to DITS_REA_RESCHED.
|ImpClearReminder||Imp||Clear outstanding reminders|
|ImpReadEnd||Imp||Indicate completion of a read by pointer|
|SdsDelete||Sds||Delete a structure|
|SdsFreeId||Sds||Free a id|
Received a dits message.
Click here for the DRAMA home page and here for the AAO home page.For more information, contact firstname.lastname@example.org