set_message_paramT_set_message_paramSetMessageParamSetMessageParamset_message_param (Operator)

Name

set_message_paramT_set_message_paramSetMessageParamSetMessageParamset_message_param — Set message parameter or invoke commands on the message.

Signature

Description

set_message_paramset_message_paramSetMessageParamSetMessageParamset_message_param sets message parameters or invokes action commands on the message.

For each call of set_message_paramset_message_paramSetMessageParamSetMessageParamset_message_param, only a single parameter can be set. However, there are two types of parameters/commands:

• Parameters/commands applicable to the entire message. In this case no keys must be specified, i.e., the parameter KeyKeyKeykeykey must be an empty tuple.

• Parameters/commands applicable to the individual keys. In this case a non-empty list of keys must be specified in parameter KeyKeyKeykeykey. The keys are processed in the same order as specified in the KeyKeyKeykeykey parameter.

Key-independent parameter names:

'remove_all_keys'"remove_all_keys""remove_all_keys""remove_all_keys""remove_all_keys":

Removes all the keys currently stored in the message and releases all the (control or iconic) data associated with those keys. The operation results in an empty message. Note that contents of GenParamValueGenParamValueGenParamValuegenParamValuegen_param_value is ignored for this parameter, while KeyKeyKeykeykey must be an empty tuple.

Key-specific parameter names:

'remove_key'"remove_key""remove_key""remove_key""remove_key":

Removes the keys specified in the KeyKeyKeykeykey parameter and releases all the (tuple or object) data associated with those keys. If an error occurs while processing one or more keys (in particular if the key is invalid), the operator attempts to continue removing as many keys as possible before reporting the failure. Note that the contents of GenParamValueGenParamValueGenParamValuegenParamValuegen_param_value is ignored for this parameter.

Execution Information

• Multithreading type: reentrant (runs in parallel with non-exclusive operators).
• Multithreading scope: global (may be called from any thread).
• Processed without parallelization.

This operator modifies the state of the following input parameter:

• MessageHandleMessageHandleMessageHandlemessageHandlemessage_handle

During execution of this operator, access to the value of this parameter must be synchronized if it is used across multiple threads.

Parameters

Example (HDevelop)

* Remove some keys
set_message_param (Message, 'remove_key', ['my_image', 'simple_string'], [])

Result

If all the operator parameters, and their values, as well as specified keys are valid, set_message_paramset_message_paramSetMessageParamSetMessageParamset_message_param returns 2 ( H_MSG_TRUE) . Otherwise an exception is raised.

Possible Predecessors

dequeue_messagedequeue_messageDequeueMessageDequeueMessagedequeue_message, create_messagecreate_messageCreateMessageCreateMessagecreate_message

Possible Successors

enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageenqueue_message, clear_messageclear_messageClearMessageClearMessageclear_message

See also

create_messagecreate_messageCreateMessageCreateMessagecreate_message, clear_messageclear_messageClearMessageClearMessageclear_message, set_message_tupleset_message_tupleSetMessageTupleSetMessageTupleset_message_tuple, get_message_tupleget_message_tupleGetMessageTupleGetMessageTupleget_message_tuple, set_message_objset_message_objSetMessageObjSetMessageObjset_message_obj, get_message_objget_message_objGetMessageObjGetMessageObjget_message_obj, get_message_paramget_message_paramGetMessageParamGetMessageParamget_message_param, enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageenqueue_message, dequeue_messagedequeue_messageDequeueMessageDequeueMessagedequeue_message

Module

Foundation