kick - Send a kick message to an action in a Drama task
Function
Send a kick message to an action in a Drama task
Description
An kick message is sent to a Drama task. A kick message is used to
cancel or otherwise modify the behaviour of an active action
previously invoked by an obey message.
The command completes immediately the message is sent unless the
-wait option is specified.
If the -success or -error options are not specified, default
handlers will be invoked which cause messages to
be output to the user.
Call
kick task action [args] [options]
Parameters
|
> | task | string | The name of the task to which the message will
be sent. The form "task@node" may be used
to send a message to a task on a remote machine.
|
|---|
|
> | action | string | Name of the action to be "kicked".
|
|---|
|
> | args | int | Sds identifier of the argument structure to
be supplied with the kick (if required).
|
|---|
|
Options
- -wait
- Wait until the kick has completed
before returning.
Recursive calls to obey/kick/etc. cannot be
made in conjunction with -wait.
- -complete command
- Execute "command" when the kick completes.
(Only one of -wait or -complete can be used).
- -success command
- Execute "command" when the kick completes
succesfully. The command will be appended with
an argument which is the Sds identifier of the
argument structure returned in the completion
message.
Note, the Sds structure referred to here is
an external item which is deleted when your
command returns. If you want to keep it about,
you should copy it using SdsCopy.
- -error command
- Execute "command" when the action completes
with
an error. The command will be appended with two
arguments - the text of the status code returned
from the task and the status code itself as an
integer
- -node
- The node on which the task resides. Assumes
this is not specified in the task argument.
- -pathtimeout seconds
- Specifies the timeout to apply to Get Path
operations. The default, -1, = no timeout.
- -timeout seconds
- Specifies the timeout to apply to actual messages.
The default, -1, = no timeout.
- -deletearg
- If an argument is supplied, the sds structure
deleted and the id freeed when this routine is
finished with it.
- -argfreeid
- If an argument is supplied, the sds id is free-ed
when this routine is finished with it.
- -argreadfree
- If an argument is supplied, the sds id is
read-free-ed and free-ed when the routine is
finished with it.
- -noflush
- If an error is signalled immediately, then
don't flush errors reported with Ers. This
gives the caller (say catch) control over error
output using ErsFlush and ErsAnnul. By default,
errors will be flushed.
Language
Tcl
See Also
DTCL manual, obey(n), pget(n),
pset(n), control(n), monitor(n),
TaskRunning(n), DitsMessage(n),
DuiExecuteCmd(3), DitsInitiateMessage(3).
Support
Jeremy Bailey, AAO
Click here for the DRAMA home page and
here for the AAO home page.
For more information, contact tjf@aaoepp.aao.gov.au