DitsKillByName - Kill a currently active action.

Function

Kill a currently active action.

Description

The routine allows an action to kill another action. The other action will complete immediatly without rescheduling. An action completion message is sent to the originator of the action being killed, with status set to that specified.

Note that an error will occur if an action attemps to kill itself (Status will be set to DITS__CANTKILLSELF).

Note, actions which are blocked using DitsActionWait() or DitsActionTransIdWait() will be worken up and the call to DitsActionWait()/DitsActoinTransIdWait() will return ither the killstat or, if that is STATUS__OK, DITS__WAIT_ACT_KILLED. The action is not killed immediately and there is actually some scope for the kill to be prevented in this case (by the action implementation hanlding the status, but that is considered rude).

For spawable actions, all actions of the same name which are active are killed.

Language

Call

(Void) = DitsKillByName (name, argument, killstat, status)

Parameters

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

>	name	Char `*`	The null terminated name of the action to kill.
>	argument	SdsIdType	An argument to return with the action completion message. This should be an Sds id. See DitsGetArgument for more details on action arguments.
>	killstat	StatusType	The status of the completion message to be sent to the originator. `DITS__ACTKILLED` may be specified if no particular status is required.
`!`	status	StatusType `*`	Modified status.

Include files

DitsSignal.h

External functions used

Dits___ActptrByName	Dits internal	Return the index to an action
DitsKillByIndex	Dits	Kill an action given the index.

External values used

DitsTask

Prior requirements

Can only be called from a Dits Application routine or a user interface response routine

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