DulMessageWArg - 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 associated 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.

Unlike DulMessageW(), the return argument (if any) is available in the argOut parameter. The user must call SdsDelete() and SdsFreeId on this when finished with it. (This allows the argument to be accessed in cases where DulMessageW() can't get at it.

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

MsgOut and ERS messages are forwarded (as of version 3.55).

Warning

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

Language

C

Call

(void) = DulMessageWArg (type,path,name,argument,timeout,argOut,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.

<argOutSdsIdType *The returned argument is written here. If a null argument is supplied, the behaviour is as per DulMessageW(). Otherwise, the SDS ID of any output argument associated with the reply is written here. The caller will be responsible for calling SdsDelete() and SdsFreeId() on this.
!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), DulMessageW(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 tony.farrell@mq.edu.au