AMX Message Exchange Manager
K
A
DAK
113
8.2 Message Exchange Use
The Message Exchange Manager supports any number of message exchanges. The
maximum number of message exchanges in a system is defined in your System
Configuration Module (see Chapter 14.5). The defined maximum sets an upper limit on
the number of actual message exchanges that can be created in your application.
A message exchange must be created by an application before it can be used. Restart
Procedures, tasks, ISPs and Timer Procedures can create exchanges. It is recommended
that only Restart Procedures and tasks be used to create message exchanges.
Create
Message Exchange Manager procedure ajmxcre is used to create a message exchange.
The Message Exchange Manager allocates a message exchange and returns a message
exchange id to the caller. The exchange id is a handle which uniquely identi fies the
message exchange. It is the responsibility of the application to keep track of the message
exchange id for future reference to the exchange.
When a message exchange is created, you must specify the maximum number of message
envelopes which are allowed to reside in each of the message exchange's four message
queues. Message queue depths may range from 0 to 32767. If a particular queue is not
used, set that queue's depth to zero. At least one message queue must have a non-zero
depth.
Message queue depth has no effect on AMX memory requirements. That is, increasing a
message queue depth does not increase memory needs. The message queue depths can
be used to limit the number of messages allowed to be pending at the message exchange
at any instant.
When a message exchange is created, you can provide a unique 4-character tag to
identify the message exchange. The tag can be used subsequently in a call to ajmxtag to
find the message exchange id allocated by the Message Exchange Manager to the
particular message exchange.
When the Message Exchange Manager creates a message exchange, it sets all of the
message exchange's message queues empty.
Send
A message is sent to a message exchange with a call to procedure ajmxsnd (or its
variations ajmxsndf or ajmxsndp). The sender must specify the message priority (0
highest; 3 lowest) thereby indicating the message queue into which the message will be
delivered. If the specified message queue is full or has been defined to have a depth of
zero, the sender will be given an error indication.
A message is a set of parameter bytes located contiguously in memory. The maximum
number of parameter bytes in a message is configured by you in your System
Configuration Module (see Chapter 14.4). These parameter bytes are completely
application dependent. The message size exactly matches that used for task mailbox
messages (see Chapter 3.9).