set_message_queue_paramT_set_message_queue_paramSetMessageQueueParamSetMessageQueueParamset_message_queue_param (Operator)

Name

set_message_queue_paramT_set_message_queue_paramSetMessageQueueParamSetMessageQueueParamset_message_queue_param — Set message queue parameters or invoke commands on the queue.

Signature

Description

set_message_queue_paramset_message_queue_paramSetMessageQueueParamSetMessageQueueParamSetMessageQueueParamset_message_queue_param sets message queue parameters or invokes action commands on the queue.

Multiple parameters and action commands can be passed through a single set_message_queue_paramset_message_queue_paramSetMessageQueueParamSetMessageQueueParamSetMessageQueueParamset_message_queue_param call, passing multiple parameter names in a tuple GenParamNameGenParamNameGenParamNameGenParamNamegenParamNamegen_param_name and corresponding values in GenParamValueGenParamValueGenParamValueGenParamValuegenParamValuegen_param_value. There must be always the same number of names and values and the values must be in the same order as the names. The parameters and action commands are applied in the same order passed in GenParamNameGenParamNameGenParamNameGenParamNamegenParamNamegen_param_name. It is important to understand that in particular in case of the action commands, it might not be possible to revert the effect of previous action commands if a later command fails, the caller therefore might need to be careful when setting multiple commands in a single call.

Currently supported parameter names are:

'abort_dequeuing'"abort_dequeuing""abort_dequeuing""abort_dequeuing""abort_dequeuing""abort_dequeuing":

Aborts any dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message operator waiting in any thread for data to be delivered. Any currently waiting call will unblock and return H_ERR_MQCNCL. Any dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message call invoked in the future will return H_ERR_MQCNCL immediately regardless of the queue status.

This command is typically needed for cleanup when any threads using the message queue and possibly blocked in dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message must be released, because it is not allowed to destroy the queue (clear_message_queueclear_message_queueClearMessageQueueClearMessageQueueClearMessageQueueclear_message_queue) while any operators might still use it. It might be necessary to wait for the completion of those threads after invoking the 'abort_dequeuing'"abort_dequeuing""abort_dequeuing""abort_dequeuing""abort_dequeuing""abort_dequeuing" command to be sure any operators using the queue are completed.

The message data currently stored in the message queue is not affected by the command. The effect of canceling any further 'abort_dequeuing'"abort_dequeuing""abort_dequeuing""abort_dequeuing""abort_dequeuing""abort_dequeuing" calls can be reset again using the 'restore_queue'"restore_queue""restore_queue""restore_queue""restore_queue""restore_queue" command.

The parameter value must be integer 1.

'restore_queue'"restore_queue""restore_queue""restore_queue""restore_queue""restore_queue":

Clears the effect of a previous 'abort_dequeuing'"abort_dequeuing""abort_dequeuing""abort_dequeuing""abort_dequeuing""abort_dequeuing" command. This means the next call to dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message will again attempt to deliver message data.

The parameter value must be integer 1.

'flush_queue'"flush_queue""flush_queue""flush_queue""flush_queue""flush_queue":

Flushes the queue. All currently enqueued messages are removed from the queue and all associated resources, in particular the tuple or object data stored in the messages, are released.

The parameter value must be integer 1.

'max_message_num'"max_message_num""max_message_num""max_message_num""max_message_num""max_message_num":

Sets the maximum number of messages that can be stored in the queue. The enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessageenqueue_message operator call would fail (H_ERR_MQOVL) if the queue would contain more messages after the operation than the defined maximum.

Setting the 'max_message_num'"max_message_num""max_message_num""max_message_num""max_message_num""max_message_num" parameter has no effect on the messages already present in the queue. No messages that are already in the queue can be removed by this operation.

The parameter value can be a positive integer or -1 if the queue size should be unlimited. The string value 'infinite'"infinite""infinite""infinite""infinite""infinite" is accepted as well. The queue size is unlimited by default.

Execution Information

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

Parameters

Example (HDevelop)

* abort waiting dequeue_message operators
set_message_queue_param (Queue, 'abort_dequeuing', 1)

Result

If all the operator parameters and their values are valid, set_message_queue_paramset_message_queue_paramSetMessageQueueParamSetMessageQueueParamSetMessageQueueParamset_message_queue_param returns 2 (H_MSG_TRUE). Otherwise an exception is raised.

Possible Predecessors

create_message_queuecreate_message_queueCreateMessageQueueCreateMessageQueueCreateMessageQueuecreate_message_queue

Possible Successors

clear_message_queueclear_message_queueClearMessageQueueClearMessageQueueClearMessageQueueclear_message_queue

See also

create_message_queuecreate_message_queueCreateMessageQueueCreateMessageQueueCreateMessageQueuecreate_message_queue, clear_message_queueclear_message_queueClearMessageQueueClearMessageQueueClearMessageQueueclear_message_queue, enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessageenqueue_message, dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message, get_message_queue_paramget_message_queue_paramGetMessageQueueParamGetMessageQueueParamGetMessageQueueParamget_message_queue_param, create_messagecreate_messageCreateMessageCreateMessageCreateMessagecreate_message, clear_messageclear_messageClearMessageClearMessageClearMessageclear_message, set_message_tupleset_message_tupleSetMessageTupleSetMessageTupleSetMessageTupleset_message_tuple, get_message_tupleget_message_tupleGetMessageTupleGetMessageTupleGetMessageTupleget_message_tuple, set_message_objset_message_objSetMessageObjSetMessageObjSetMessageObjset_message_obj, get_message_objget_message_objGetMessageObjGetMessageObjGetMessageObjget_message_obj

Module

Foundation