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

C

Call

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

Parameters

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

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

Include files

DitsSignal.h

External functions used

Dits___ActptrByNameDits internal Return the index to an action
DitsKillByIndexDits 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

See Also

The Dits Specification Document, DitsKillByIndex(3), DitsSignalByName(3), DitsGetActIndex(3)

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