This function sends a queue message, for a specified user(s), to the server message queue. The message may then be retrieved by that user (or users) with the RetrieveMessage function.

The message is supplied as the first argument, MessageExpression. The second and third arguments, destination and NameExpression, identify the user or users to which the message is directed. Destination may take one of the following values:

If omitted, destination defaults to ToAnyone.

The last argument, CategoryExpression, may be used to identify the type of message sent. The value is user defined and may take any value upto sixteen characters long. The message category has no meaning to Equinox; it exists only to enable the developer to group messages into different types.

If the message is not accepted for transmission, then an error number is stored in the SysError system workarea. Note that messages sent to connections or users who are not logged in will not be accepted.

Note that when the message has been sent, its identifier may be retrieved using the MessageId function.

The following example shows how a client could be turned into a "report server". The report server is dedicated to running reports, requested by other clients. The clients request a report by sending a message, of category "report" to the report server. The report server intercepts the messages by scanning the server queue with a method attached to the Not Busy event on a form.

The following example shows how a client may request a report, whose file name is "ORDERS.REP".

QueueMessage "customer\orders.rep", ToUser, "rsrvr", "report"

The next method is attached to a Not Busy event on the report server, where ReportName is a local workarea.

if MessagesWaiting > 0 then

RetrieveMessage, ReportName ,"report"
if not syserror then Execute Report ReportName

end if