DulMessageW - Send a message to task, blocking the current action until it is complete.

Function

Send a message to task, blocking the current action until it is complete.

Description

This function sends a message to a task. The invoking action or UFACE context is blocked (using DitsActionWait() or DitsUfaceWait). to await the completion of this message. Such blocking allows the task to continue processing other actions and UFACE context messages.

In in an action context, action is NOT unblocked when a KICK is received for the action which invokes it, but the Kick handler may cause the action to be rescheduled and the action will then be unblocked when the reschedule occurs. This routine will return the status DUL__UNEXPECTED if this occurs.

Note that if another action/UFACE context calls this or assocaited routines (anything that invokes DitsActionWait/DitsUfaceWait) while this call is outstanding, then that call must unblock before this call will be unblocked - i.e. first in last out.

As of DUL version 3.40, we use the new DitsActionTransIdWait() and DitsUfaceTransIdWait() instead of the older versions which don't allow the transaction ID to be specified. This means we only return when the transaction completes or the timeout occurs, regardless of what other events come in. This is normally the required behaviour.

Warning 1: When run in UFACE context when outside the DRAMA message receive loop (say DitsMainLoop() etc. has not been called) then DitsGetArgument() will allways be nil on return from this routine. In other cases (actions content and UFACE context in reponse to a message) on return from this routine, DitsGetArgument() have the return argument if any.

The inconsistency is due to a potential resource leak. Please see DulMessageWArg() to avoid this problem.

Warning 2: If the target action is expected to return a large argument structure, then this function may be quite inefficent as it does an SdsCopy on the structure. It is suggested that normal resheduling be used in such cases.

Language

C

Call

(void) = DulMessageW (type,path,name,argument,timeout,status)

Parameters

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

>typeDitsMsgTypeThe type of message to send. One of

DITS_MSG_KICK Kick an action
DITS_MSG_OBEY Start an action
DITS_MSG_GETPARAM Get a parameter value
DITS_MSG_SETPARAM Set a parameter value
DITS_MSG_CONTROL Dits control message
DITS_MSG_MONITOR Dits parameter monitor message

See DitsInititateMessage for full details of each message type.

>pathDitsPathType *The path to the task as returned by DitsGetPath or DulGetPathW.
>namechar *The name associated with the message. Depends on message type but for OBEY and KICK, this is the action name.
>argumentSdsIdTypeAn argument to the message. This should be an Sds id. See DitsGetArgument and DitsPutArgument for more details on action arguments.
>timeoutdoubleIf positive, this is a timeout to apply to the obey operation.

!statusStatusType *Modified status.

Include files

Dul.h

Prior requirements

Dits must have been initialised.

See Also

Dul library document, DulGetPathW(3), DulLoadW(3), DitsInitiateMessage(3), DitsActionWait(3), DitsUfaceWait(3), DulMessageWArg(3), Dits specification.

Support

Tony Farrell, AAO

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

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