The following message types can be sent
| DITS_MSG_KICK | Kick an action |
|---|---|
| DITS_MSG_OBEY | Start an action |
| DITS_MSG_GETPARAM | Get a parameter value |
| DITS_MSG_MGETPARAM | Get multiple parameters. The name item is ignored (supply as a zero length string). You supply the names of the parameters the values of which are to be returned in the argument structure as a character array containing the space separated names or a set of character string arguments. |
| DITS_MSG_SETPARAM | Set a parameter value |
| DITS_MSG_CONTROL | Dits control message |
| DITS_MSG_MONITOR | Dits parameter monitor message |
This is the lower level routine called by routines such as {\tt DitsObey}, to actually send the message. Routines such as {\tt DitsObey} provide a simpler interface, but the use of this routine can be more efficent when the same message is being sent repeatly. In this case, setup the message structure only once to save time.
The control type messages are designed to perform special functions in the Dits fixed part. The following names are currently defined
| DEFAULT | Set and return the default directory. The argument, if supplied, contains a string in its first item, which is the name of the requested default directory. The new default is returned in the completion message. If the argument is not supplied, then the current default directory is returned. |
|---|---|
| MESSAGE | Requires an argument which should be an message code, as per the Mess routines. The text associated with the message code is fetched and returned in the completion message. The idea of these message is to provide a general facility for translating message codes in the task which knows about the message codes. DEBUG -> Sets the DITS internal logging level. If no argument is supplied, then level DITS_LOG_BASIC is turned on. Otherwise, the argument should be an integer value which is a mask of the values which may be supplied to DitsSetDebug(3). DUMPPATHS -> Dump details of all paths used by this task to stdout. DUMPTRANSIDS -> Dump details of all outstanding transaction ids known to this task to stdout. DUMPMON -> Dump details of current parameter monitors to stdout. DUMPACTACTIVE -> Dump details of active actions to stdout. DUMPACTALL -> Dump details of all actions to stdout. VERSIONS -> Output DRAMa, DITS and IMP version information. LOGNOTE -> If we have a logging system - write the argument (which should be string in an item named Argument1), to the log file. LOGFLUSH -> If we have a logging system and it supports flushing, flush it. LOGINFO -> Reports details of the logging system, iff a logging system has been enabled and supports this call. SDSLEAKCHK -> Allocates and reports the number of an SDS ID. This provides a way of working out if a task is leaking SDS ID's. If you run this command a number of times, during which you don't expect any SDS ID's to have been allocated long term, but this number increases, then your task is leaking SDS ID's. |
Sending a control message with an invalid name will cause the names of the valid names to be printed on stderr.
The monitor message types are designed to perform parameter monitoring. The following names are currently defined
| START | Start monitoring. A monitor id is returned in a trigger message with status DITS__MON_STARTED which should be in future messages. The optional argument is a list of parameter names specifing the parameters to be monitored. |
|---|---|
| FORWARD | Start monitoring but forward the details of parameter changes with an obey message to the task specified in the first argument, using the action name specified in the second argument. A monitor id is returned as per START and an optional list of parameter names can be specified as additional parameters. |
| ADD | Add the parameters who's names are listed in the second argument onward to the list of parameters being monitored. The first argument is a monitor id as returned from a start or forward message. |
| DELETE | Delete the specified parameters from the list of those being monitored. The first argument is a monitor id as returned from a start or forward message. |
| CANCEL | Cancel monitoring . The argument is the monitor id for which monitoring is being canceled. |
Once non-forward monitoring is started, trigger messages will be recevied for each parameter change, in the context of the START message transaction. The status will be DITS__MON_CHANGED and the argument will be an Sds item of the same name as the parameter being changed and containing the new value.
For forward style monitor, an obey message is sent to the specified task, using the specified action name, each time the parameter value changes.
Monitoring only works if the target task's has a parameter system and that parameter system has enabled monitoring. Each parameter can be monitored by any number monitor transactions.
The parameter name "_ALL_" is special and indicates that all parameters are to be monitored. Note that this is incomplatible with the DITS_M_SENDCUR flag. If you want to monitor all parameters and fetch their current values, use a parameter get message with the name _ALL_ to get the initial values.
If when trying to send a monitor message, the buffers in the target task (the parent task for normal monitors and the destination task in forward messages) overflow, then the message is not sent. However, except when a transaction is explictly monitoring all parameters (using the _ALL_ name), the standard monitor software will request to be notified when the buffers in the target task empty. When the notification comes in, It will then send a monitor message giving the value of the parameter at that time. This ensures last value of the parameter gets though, regardless of buffers being overflowed.
For GET and MGET messages, the names _ALL_ and _NAMES_ are special. If _ALL_ is specified, the entire parameter system is returned. If _NAMES_ are specified it requests that a list of names be returned. In this case an SDS structure of type is returned. This will contain one item, an array with each of the names in it. If you wish to get a parameter with a name that is longer then DITS_C_NAMELEN (the length of message->name) then you should use a MGET message and specify the name in the argument structure.
For SET messages, if the name is to be longer then DITS_C_NAMELEN, then specify the name _LONG_ and then specify 2 items in the SDS message.argument structure. The first of these should be the a character string giving the name of the parameter and the second should be the value.
If the action you are obeying is spawnable (see DitsPutActions(3)) then kicking is requires a special kick message. There are two alternatives, the first is to use the transid value returned in the obey call to create an argument structure to be supplied to the kick message, This is done using DitsSpawnKickArg(3) or DitsSpawnKickArgUpdate(3). Other details can be added to this structure if required and will be available to the kick with DitsGetArgument()- through an item named KickByTransId should be ignored by application code.
Alternatively, if the action index of the started action may used, by specifying an argument structure to the message containing an item named KickByIndex and which contains this acton index value. The subsidiary action can use DitsGetActIndex(3) to gets its action index. How the value gets form the subsidiary task to the one which wants to sent the message is up to the application.
Unless transid is null, the sender should reschedule (or block using DitsActionWait(3)/DitsUfaceWait(3) to await responses. See DitsGetEntReason(3) for a list of possible entry reasons when responses arrive (not all the values will occur due to responses from sending a messages).
If a response has an argument (SDS) associated with it, the normally DitsGetArgument(3) can be used to get the argument. Action (Obey) complete messages would have put that argument using DitsPutArgument(3).
The status of a response message can be returned using DitsGetEntStatus(3), when the reaponse is received. Of particular note are the following status codes.
| DITS__ACTACTIVE | An obey message was sent, but the target action is already active and is not a spawnable action. |
|---|---|
| DITS__COMPSENDERR | A message that was to be sent with the completion message is too big to ever fit in the buffer. The task which set up the buffer should increase the buffer sizes, or reduce the size of any argument to the message. |
| DITS__NOSPACE | The buffer for the reply does not have sufficent space for this message at this time. |
| DITS__ACTNOTACT | An attempt was made to kick an action which is not currently active. |
| DITS__NOKICK | An attempt was made to kick an action which has no kick handler. |
| DITS__TASKDISC | A task disconnected (died) whist processing the message. |
| DITS__MACHLOST | All connections to the machine on which the task is running have been lost. |
| DITS__MON_STARTED | Indicates a monitor transaction has started. |
| DITS__MON_CHANGED |
Indicates a monitor transaction parameter value
changed message.
|
| > | flags | long int | A flag word controlling some options. The
priority bit (DITS_M_PRIORITY) can be set to
indicate that this message should be sent to the
top of the queue of messages being sent to
the target task. Note that only relatively short
messages should be sent in this way , as the
Imp priority buffers are limited in size. (It is
recommend that the message not include an argument,
in order to meet this restriction.
|
|---|---|---|---|
| > | path | DitsPathType | Path to the task involved. |
| < | transid | DitsTransIdType * | Transaction id for the transaction started. If an address of zero is supplied, then don't create a transaction id. In this which case we will never be notified of errors one the message is sent. As a special case, if you specify a transid of 0 when sending a Kick message, then any Informational/Error or Trigger messages initiated during the handling of the initial Kick message will be directed towards the initiator of the Corresponding Obey message. |
| ! | message | DitsGsokMessageType * | The message
details. The
following detail should be set
|
| flags | (int) Mask of flags. Set DITS_M_ARGUMENT if an argument is supplied. Set DITS_M_SENDCUR if a monitor message (START/FORWARD/ADD) and you want the current value of the parameter sent immediately. Set DITS_M_REP_MON_LOSS to cause the reporting of monitor messages which are lost due to waiting for buffer empty notification messages to arrive. This should be consider if the loss of monitor messages is significant to your application. In general, it is not as the system ensures the last parameter update gets though. |
|---|---|
| argument | (SdsIdType) The Sds id of the argument. Ignored if flags is not set to DITS_M_ARGUMENT. For actions etc. this value will be available to using DitsGetArgument(). |
| type | (DitsMsgType) The message type. As listed above. |
| name | (DitsNameType) The name of the action to initialite or the parameter to set. Set this value using the macro "DitsNameSet(destin,source)". where source is the name you wish to setup and destin is the field. |
Other fields may be modified during the send, so this routine should be able to write to this location.
| ! | status | StatusType * | Modified status.
|
|---|---|---|---|
Click here for the DRAMA home page and here for the AAO home page.
For more information, contact tony.farrell@mq.edu.au