6 Sending a Command

Having obtained a path, ams_send() can be used to send a command message to the task identified by that path – the message_function argument is set to MESSYS__MESSAGE. If ams_send() succeeds, it starts a new transaction and returns a transaction id (messid) which remains valid for the duration of the transaction. The task which sends the message becomes the ‘master’ and the one which receives it becomes the ‘slave’ for the transaction.

Command messages are designed for use with ADAM tasks but this does not preclude their use for other purposes (see the example in Section A). The other arguments to ams_send are packed into the message and are unpacked by AMS at the other end. What the slave task does with them is up to it – AMS generally has no interest in the other arguments of ams_send().

There is one exception to this – if the message_context is OBEY, the receiving end will allow the transaction to include further messages from the master task as part of the same transaction. This enables the slave to reply with requests (prompts) for parameter values and receive replies from the master.

ADAM use of the other arguments is as follows:

message_status

Should be SAI__OK.

message_context

One of the following constants, defined in adamdefns.h:

GET

To request a parameter value.

SET

To set a parameter value.

OBEY

To obey an action in the task.

CANCEL

To cancel an action in the task.

CONTROL

To control/enquire the task environment.

message_name

Name of task action or parameter.

message_length

Length of message_value.

message_value

Context-dependent values.