DitsUfaceTransIdWait - Blocks the current UFACE context and waits for a message to be received.

Function

Blocks the current UFACE context and waits for a message to be received.

Description

The current UFACE context is blocked and a message receive loop entered. Other actions and UFACE messages can be processed as normal. When a message concerning this context is received, the context is unblocked and will continue. The current entry details (DitsGetArgument() DitsGetEntInfo() etc) will then be for the first message received for this UFACE context. The count variable will return the number of other messages still remaining to be processed.

NOTE - the argument retrived by DitsGetArgument() will be an SdsCopy(3) of the original argument structure. As a result, you should not use DitsUfaceWait(3) to hangle 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().

Language

C

Call

(void) = DitsUfaceTransIdWait(flags,timeout,info, transId, count,status);

Parameters

(">" input, "!" modified, "W" workspace, "<" output)

>flagsintA 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 the the info block.
DITS_M_AW_DONT_BLOCK 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

detailssuch 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.

>timeoutDitsDeltaTimeType *If non-zero, the address of a reschedule delay.
>infoDitsUfaceWaitInfoType *A variable initialised by calling DitsUfaceWaitInit prior to a sequence of calls to this routine. It is used to maintain details about this context.
>transIdDitsTransIdTypeIF 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.
<countint *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.
!statusStatusType *Modified status. WARNING - status of message receiving code, not message status. To get the status of the received message, fetch the value from DitsGetEntStatus().

Include files

DitsSys.h, DitsInteraction.h

External functions used

ImpReadEndImp Indicate completion of a read by pointer
SdsDeleteSds Delete a structure
SdsFreeIdSds Free a id
DitsMsgReceiveDits Received a dits message.
DitsUfaceTimerDits Create a UFACE context timer.
DitsUfaceTimerCancelDits Cancel a UFACE context timer.

External values used

DitsTask - Details of the current task

Prior requirements

Can only be called at UFACE context.

See Also

The Dits Specification Document, DitsUfaceCtxEnable(3), DitsActionWait(3), DitsUfaceWaitComp(3), DitsUfaceWaitInit(3) .

Support

Tony Farrell, AAO

Click here for the DRAMA home page and here for the AAO home page.

 For more information, contact tjf@aao.gov.au