DitsSignalByIndexPtr - Trigger the rescheduling of an action.

Function

Trigger the rescheduling of an action.

Description

The routine allows an action to trigger the rescheduling of another action in the current task.

Although this could in theory be done by DitsKick, by using DitsSignal series you avoid having to have a path to this task. In addition, this routine can be used when there is no action context (such as in an interrupt serivce routine).

The target action may be awaiting rescheduling for any reason (having put a request of DITS_REQ_WAIT, DITS_REQ_SLEEP, DITS_REQ_MESSAGE or DITS_REQ_STAGE).

Since this routine is often used for communication between interrupt routines and main line code, the message is sent as a high priority message and will thus be put a the begining of the incomming message buffer.

In the case of interrupt service routines, you probably need to first enable the appropriate Dits task. See DitsGetTaskId(), DitsEnableTask() and DitsRestoreTask().

Note, as this routine is often used to allow non-DRAMA parts of a program to communicate with a DRAMA program, applications often get into trouble if DitsSignal... fail. I recommend you always check status after such a call and report errors using an appropriate system error routine. For VxWorks interrupt handlers, this is the logMsg() call. For WIN32, this is probably the MessageBox() call. For most others it is fprintf() to stderr. The most common error is to fail to set status to STATUS__OK before calling these routines.

WARNING 1: If your are sending signals from an ISR routine and sending messages to your own task from main line code, you should specify the flag DITS_M_SEP_SIG_BUF when you call DitsAppInit(). A failure to do this could result in buffer corruption.

DO NOT (in the current version) send messages using DitsSignal() from both an ISR and main line code if they could occur at the same time. (A later version may fix this if there is demand).

WARNING 2: Under VxWorks, do not call DitsSignal() from and ISR or another task if your task has specified the DITS_M_X_COMPATIBLE. On VxWorks, there is a rare case using this notification method which may cause blocking. A warning will be output to the VxWorks console if you are doing this.

Also see DitsSignalByName().

Language

C

Call

(Void) = DitsSignalByIndexPtr (index, argument, sigArg, status)

Parameters

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

>indexlong intThe index to the action to kick. This must be a value returned by DitsGetActIndex().
>argumentSdsIdTypeAn argument to the action. This should be an Sds id. See DitsGetArgument for more details on action arguments. Note that for this routine, no copy is made of this argument structure - this argument structure will be deleted after the action is invoked.
>sigArgvoid *A pointer which will be assoicated with the signal. The action can fetch this using DitsGetSigArg(3).
!statusStatusType *Modified status.

Include files

DitsSignal.h

External functions used

Dits___SendTapDits internal Send a tap message

External values used

DitsTask

Prior requirements

Can only be called from a Dits Application routine

See Also

The Dits Specification Document, DitsKillByIndex(3), DitsSignalByNamePtr(3), DitsGetActIndex(3), DulIntInit(3), DulIntSignalByIndex(3), DitsGetSigArg(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