create_message — Create a new empty message.
create_message( : : : MessageHandle)
create_message creates a new empty message. The output parameter
MessageHandle is a handle to the newly created message
and is used to identify the message in any subsequent operator
call using the message.
The message serves as a dictionary-like container that can be passed
between the threads of an application using asynchronous message queues.
Alternatively, HALCON also provides dictionaries (
group parameters in programs and procedures.
Messages can store an arbitrary number of entries, each having its unique
key (string or integer) and associated value. Each key can refer either to
a control parameter tuple or to an iconic object. These data are stored to
the message using
respectively, from where they can be retrieved again using
The data stored in the message are always deep copies of the original
data, being it control parameters or objects. The original data
can thus be reused immediately after the
set_message_obj calls without affecting the message.
Notable exceptions are handles which are treated as regular integer
values by HALCON, therefore storing any handle in the message
will copy the handle value, but not the resource behind the handle.
As mentioned above, the messages can be passed between the threads of an
application using asynchronous message queues.
The data can be appended to the queue by multiple producer threads
enqueue_message and retrieved from the queue
by multiple receiver threads using
All these operations are internally properly synchronized.
Therefore, the queue can be safely accessed by all producers
and consumers without any explicit locking.
All the enqueued messages are copied by the
enqueue_message operation. The original message(s) can thus be
immediately reused after the
enqueue_message call without affecting
the enqueued copy.
Handle of the newly created message.
Number of elements: MessageHandle == 1
MessageHandle != 0
MessageHandles :=  for idx := 0 to 4 by 1 create_message (MessageHandle) MessageHandles[idx]:= MessageHandle endfor * ...
Returns 2 (H_MSG_TRUE) unless a resource allocation error occurs.