Directory listing of http: uap.unnes.ac.id ebook biblebook Visual Basic 6 com & Library Books

19

C H A P T E R

Using M essage
Queues

✦

✦

✦

✦

In This Cha pter

I

n this c hapter, I want to talk abo ut Mic ro so ft Message
Queues, inc luding what they are, ho w they wo rk, and when

they might be useful fo r yo ur applic atio ns.

Intro ducing the
Q ueuing O bject
Mo del
Accessing
messag e queues

How M essage Queuing Works
Me ssage que uing is a to o l that helps two pro grams c o mmunic ate with eac h o ther in an async hro no us fashio n. This means
that a c lient pro gram c an send a request to a server and then
c o ntinue pro c essing witho ut waiting fo r the server pro c ess to
c o mplete. When the server pro c ess has finished pro c essing
the request, it will return the message to the c lient pro gram,
whic h will be no tified with the respo nse it available to be pro c essed.
Note

Well, kinda, sorta: While not strictly a part of the COM+
program m ing environm ent, Microsoft Message Queuing
w orks closely w ith COM and COM+ com ponents to im plem ent high-perform ance applications.

Synchronous processing
No rmally, when yo u are using a COM c o mpo nent and yo u
issue a metho d, o r request the info rmatio n in a pro perty, yo ur
pro gram must wait until the metho d o r pro perty returns c o ntro l to yo ur pro gram. This is c alled synchro no us pro ce ssing.
In sync hro no us pro c essing, the c lient pro gram begins by sending a request to the server to perfo rm a spec ific task. The
server pro gram rec eives the request, perfo rms the task, and
returns the result bac k to the c lient. During the time the server
is pro c essing the c lient’s request, the c lient pro gram is in a wait

Building client and
server pro g rams
Viewing messag e
queue info rmatio n

✦

✦

✦

✦

400

Part IV ✦ COM + Transactions and M essage Queues

state, where it c an’t perfo rm any pro c essing. It will o nly resume pro c essing after the
server has returned its respo nse (see Figure 19-1).
Tip

Synchronous processing made simple: When thinking about synchronous processing, visualize how a Web brow ser w orks. The URL is used to generate a
request to the Web server and then the brow ser w aits for the Web page to be
returned.

Request
Response
Client

Server

Figure 19-1: Processing a synchronous request

Asynchronous processing
In so me c ases, it’s useful fo r yo ur pro gram to issue a request fo r info rmatio n and
then perfo rm o ther tasks while yo ur pro gram waits fo r the respo nse. This is c alled
asynchro no us pro ce ssing.
In async hro no us pro c essing, the c lient pro gram begins by sending a request to the
server to perfo rm a spec ific task and then resumes its no rmal pro c essing. The server
rec eives the request, pro c esses it, and returns the result. When the result is rec eived,
the c lient pro gram is no tified that the result is available and ready fo r the c lient pro gram to use (see Figure 19-2).
Tip

Asynchronous processing made simple: One w ay to understand how asynchronous processing w orks is to com pare it to electronic m ail. You can send a
m essage to som eone requesting a piece of inform ation and then continue reading
and sending other e-m ail until you receive a response to your original m essage.

Chapter 19 ✦ Using M essage Queues

Client

Server

Client
Request
Queue
Client
Response
Queue

Request

Response

Server
Request
Queue
Server
Request
Queue

Figure 19-2: Processing an asynchronous request

Sinc e the c lient is no lo nger tightly c o upled to the server, the server has the freedo m to pro c ess requests in the mo st effic ient manner. Sinc e it is quite po ssible that
multiple c lients will be sending requests, all o f the messages are sto red in a queue
as they are rec eived. As the server finishes pro c essing o ne request, it will pull the
next request fro m the queue. This ensures that all o f the messages are pro c essed in
the o rder in whic h they were rec eived.

Benefits of message queuing
Using message queues will inc rease the c o mplexity o f yo ur applic atio n. In additio n,
no t all applic atio ns will benefit fro m using message queuing. Ho wever, the benefits
o f message queuing may o utweigh the extra c o mplexity.

Component availability
Just bec ause yo u have a full-time c o nnec tio n to the server do esn’t mean that the
server will always be available. The server’s o perating system o r the applic atio n
running o n the server may have c rashed. Netwo rking pro blems are pro bably mo re
c o mmo n, espec ially if the server is lo c ated in ano ther building o r ac ro ss the c o untry fro m yo ur c lient mac hines.

401

402

Part IV ✦ COM + Transactions and M essage Queues

If yo u are unable to reac h the server fo r any reaso n, all o f the requests are buffered
lo c ally until the server c an be reac hed. When the server bec o mes available, the
info rmatio n that was buffered lo c ally will be transmitted to the server fo r pro c essing. Also , any results that the server may have pro c essed will be rec eived into lo c al
sto rage fo r the c lient to pro c ess.

Component performance
By queuing requests fo r pro c essing, the user need no t wait fo r the server to finish
pro c essing o ne request befo re starting o n the next request. Thus, yo u c an c reate
yo ur applic atio n to prio ritize ho w the pro c essing is do ne. This is impo rtant when
yo ur server bec o mes o verlo aded. Tho se tasks that need an immediate respo nse,
suc h as c hec king invento ry levels, c an be handled as a no rmal COM+ o bjec t. Tho se
tasks that are no t as time-sensitive, suc h as printing an invo ic e, c an be deferred
until the server is less busy by using message queuing.

Component lifetimes
Delays c aused by transmitting info rmatio n o ver the netwo rk and interac ting with
the user extend the amo unt o f time that an o bjec t ac tually exists inside the transac tio n server. By using message queuing, the exc hange o f info rmatio n is handled o utside the transac tio n server. This means that the o bjec t exists fo r far less time than
it wo uld witho ut using message queuing. This translates into better perfo rmanc e in
the transac tio n server, bec ause fewer system reso urc es are needed to pro c ess the
ac tual transac tio n.

Disconnected applications
If yo u c reate queues that go in bo th to the server and to the c lient, yo u may no t
need a full-time c o nnec tio n to the server. Requests c an be queued up until a c o nnec tio n to the server is established. Then the requests are transmitted to the
server fo r pro c essing using the server queue. Any respo nses that the server has fo r
the c lient c an be queued in the c lient queue. When the c o nnec tio n is established,
bo th queues will be transmitted to the o ther mac hine. If the c o nnec tio n remains up
fo r eno ugh time, the server may ac tually be able to respo nd to the requests sent by
the c lient and return them via the reverse queue.

M essage reliability
Message queuing relies o n a database to sto re the requests. This ensures that the
requests are pro tec ted fro m system failures. If and when the database needs to be
rec o vered, the requests in the queues wo uld also be rec o vered. Sinc e the time to

transmit and add the request to a queue is muc h less than the time a no rmal o bjec t
wo uld exist, it is less likely that a failure wo uld o c c ur in the middle o f a spec ific
request.

Chapter 19 ✦ Using M essage Queues

Server scheduling
Ano ther advantage o f message queuing is the ability to shift the wo rk sitting in a
queue to a time when the server is less busy. Thus, message queues have the ability
to duplic ate the batc h-pro c essing features o f the mainframe wo rld by making it
easy to shift wo rk to a less busy time.

Load leveling
One pro blem with mo st server-driven applic atio n systems is that their wo rklo ad
c an vary greatly o ver time, whic h may have an adverse impac t o n perfo rmanc e. In a
sync hro no us enviro nment, a server c an easily get o verwhelmed fo r a few mo ments
at a time. If this happens o c c asio nally, the server c an c atc h up and no bo dy will
no tic e. On the o ther hand, if this happens frequently, the o perating system and the
server applic atio n will be fo rc ed to spend extra reso urc es managing the extra wo rk,
whic h means that there are less reso urc es to pro c ess the extra wo rk.

This extra o verhead c an be eliminated by using message queuing (async hro no us
pro c essing). Yo u wo uld tune the server and the applic atio n to get the highest perfo rmanc e. Then yo u wo uld stage the requests in a message queue until the server
c an pro c ess them. Mo st o f the time, the requests wo uld be pulled fro m the message
queue as fast as they arrive. Ho wever, when the requests arrive faster than the
server c an pro c ess them, they will remain in the message queue until the server
c an pro c ess them.
In real terms, the slight penalty impo sed by using message queuing will no t make a
big differenc e in the time it takes to pro c ess a request until the server bec o mes o verlo aded. Then, depending o n ho w o verlo aded the server is, using message queuing
will inc rease the time to pro c ess eac h request. Ho wever, bec ause the applic atio n is
c o ntinuing to pro c ess requests at o ptimal speed, the time the request spends in the
message queue, plus the time it takes the applic atio n to pro c ess the request, will
mo st likely be less than the time it takes to pro c ess the request while the server
is o verlo aded.
Note

Too much is just right: A long tim e ago, I ran into a situation w here one of the
com puters I w as responsible for w as running at m axim um capacity. The CPU utilization w ould stay at 100% for several m inutes at a stretch. Response tim e w as
horrible. Upgrading to a CPU that w as tw ice as fast solved the problem . How ever,
the CPU utilization w as about 40%, rather than the expected 50%. After a lot of
digging and analysis, I determ ined that the old CPU w as w asting nearly 20% of its

capacity trying to m anage the extra requests. With the faster CPU, the overload
condition never arose and the CPU cycles w ere never w asted. While it is not
alw ays possible to double your CPU capacity, you m ay be able to use a tool like
m essage queuing to ensure that the your CPU isn’t w asting extra cycles trying to
m anage too m uch w ork.

403

404

Part IV ✦ COM + Transactions and M essage Queues

M icrosoft M essage Queuing
In o rder to use message queues in a Windo ws enviro nment, yo u need a piec e o f
so ftware c alled Mic ro so ft Message Queuing (o ften abbreviated MSMQ). It runs o n
Windo ws 9x, Windo ws NT, and Windo ws 2000, tho ugh yo u may need the appro priate patc hes to run it. It is c o nsidered a base c o mpo nent o f these o perating systems;
thus, there isn’t a separate c harge fo r the so ftware.

Requests and responses
A request is sent to the server using an o bjec t c o ntaining all o f the info rmatio n
needed to pro c ess the request. The o bjec t must be persistable and be less than
fo ur megabytes in length.
There are fo ur basic respo nses to a request.

✦ No response is necessary – this means that the message sent by the c lient
either do esn’t need a respo nse o r the respo nse will be returned using a different tec hnique. Fo r instanc e, the message sent by the c lient may request a
repo rt that will be returned by e-mail.

✦ Trigger an event in the client application – this means that the server applic atio n will fire an event in the c lient pro gram when the server applic atio n has
finished pro c essing the message.

✦ Use a synchronous method to check on the status – this means that the
server applic atio n may expo se a pro perty that a c lient applic atio n c an ac c ess
to determine if their message has been pro c essed.

✦ Use message queuing to receive a response – this is pro bably the mo st c o mmo n way to determine the o utc o me o f pro c essing a request. Co nsider the c ase
o f a salesperso n that enters o rders into a lapto p c o mputer while at a c usto mer’s
site. At the end o f the day, the salesperso n c o uld c o nnec t the lapto p to the c o mpany’s applic atio n server. Then MSMQ wo uld transfer the lo c al messages to the
message queues o n the server, while do wnlo ading any respo nses fro m the
server into lo c al sto rage fo r the salesperso n to bro wse at his o r her leisure.

Types of queues
Queues are really just sto rage that is allo c ated to c o ntain messages alo ng with the
info rmatio n needed to manage the info rmatio n in the queue. Different types o f
requests rec eive different types o f respo nses. Also , in o rder to o perate a message
queue, the so ftware o n the c lient and server ends o f the message queue need to
exc hange info rmatio n. This info rmatio n is typic ally sent using message queues.

Chapter 19 ✦ Using M essage Queues

There are six basic types o f queues. The type o f queue dic tates ho w the queue will
be used, but underneath, the same basic tec hno lo gy is used to suppo rt all o f these
types:

✦ Message – this is the mo st c o mmo n type o f queue and is used primarily by
applic atio ns. Clients c an send messages to the queue, while server applic atio ns c an retrieve messages fro m the queue.

✦ Administration – this type o f queue is used by an applic atio n to retrieve status info rmatio n abo ut messages in a message queue. Fo r example, an
ac kno wledgement message indic ates that a message was rec eived o r retrieved
fro m the applic atio n at the queue’s destinatio n.

✦ Response – this type o f queue is used by c lient applic atio ns to rec eive
respo nses fro m the server applic atio n.

✦ Report – this type o f queue trac ks the pro gress o f the messages as they mo ve
thro ugh the system.

✦ Journal – this type o f queue ho lds messages that have been retrieved at their
destinatio n.

✦ Dead-letter – applic atio n messages that c an’t be delivered are sto red in this
type o f queue.

Public and private queues
Queues c an also be labeled as public o r private. Public que ue s are registered in the
Ac tive Direc to ry and c an be lo c ated by anyo ne with ac c ess to the Ac tive Direc to ry.
Yo u c an searc h fo r vario us pro perties o f a queue in the Ac tive Direc to ry so that yo u
c an lo c ate the c o rrec t o ne. Thus public queues c an o nly be implemented o n a
Windo ws 2000 Server based system.
Co mbining the name o f the c o mputer with the name o f the queue c reates the name
o f a public queue. So , the queue MyQueue o n the Athena wo uld be kno wn as
Athena\MyQueue.

Note

Actively seeking directory information: The Active Directory facility in Window s
2000 Server is a tool that stores inform ation about the resources on the local com puter, or resources that can be found elsew here on the netw ork. Window s 2000
m akes extensive use of this facility to store inform ation about the operating system ,
such as user nam es, like public queues, other specialized services, and so on.
Private queues are registered on an individual com puter and can be found by anyone w ho know s the nam es of the com puter and the queue. You m ust also include
the keyw ord \Private$ in the nam e of the queue, so a private queue on Athena
called MyQueue w ould be w ritten as Athena\Private$\MyQueue.

405

406

Part IV ✦ COM + Transactions and M essage Queues

By default, all queues are public . To make a queue private, yo u must inc lude
\Private in the name o f the queue when it is c reated. Yo u must have ac c ess to
an Ac tive Direc to ry server to do this, ho wever. No te that private queues c an be
c reated o n Windo ws 98- and Windo ws NT-based mac hines.

M essage queuing and COM + transactions
COM+ transac tio ns using message queues wo rk auto matic ally with the COM+ transac tio n server and the ObjectContext o bjec t. Getting the ObjectContext o bjec t
and perfo rming the SetComplete, o r SetAbort, metho d auto matic ally ro lls bac k
any o peratio ns yo u made to the queues. In o ther wo rds, no messages are remo ved
fro m the queues o r physic ally sent until the transac tio n is either c o mmitted o r
ro lled bac k.
There is o ne big issue abo ut using message queues and transac tio ns. While inside
a transac tio n, yo u c an o nly send messages to transac tio nal queues — queues that
were c reated with the IsTransactional parameter o f the MSMQQueueInfo.Create
metho d set to True. Also , any messages that are sent auto matic ally have their
MSMQMessage.Priority value set to zero . This ensures that the messages are pro c essed in the o rder in whic h they were rec eived.
The message queues also inc lude their o wn versio n o f transac tio n suppo rt in
c ase yo u do n’t want to use the COM+ transac tio n server o r want to wo rk o utside
its c o ntro l. Yo u need to use the MSMQCoordinatedTransactionDispenser to
begin a transac tio n while under c o ntro l o f the COM+ transac tio n server. Use the
MSMQTransactionDispenser o bjec t if yo u’re no t under c o ntro l o f the COM+ transac tio n server. Then use the MSMQTransaction o bjec t to either c o mmit the transac tio n o r abo rt the transac tio n.

M essage Queuing Object M odel
Like mo st Windo ws to o ls, the MSMQ is ac c essed via a series o f COM c o mpo nents.
Figure 19-3 sho ws a brief o verview o f the o bjec ts and ho w they are related to eac h
o ther.

✦ MSMQQuery – is used to searc h the Ac tive Direc to ry fo r public queues. It
returns an MSMQQueueInfos c o llec tio n c o ntaining the set o f message queues
that met the searc h c riteria.

✦ MSMQQueueInfos – c o ntains a set o f MSMQQueueInfo o bjec ts. This c o mpo nent c o ntains the results o f an MSMQQuery o peratio n.

✦ MSMQQueueInfo – is used to c reate and o pen queues as well as c o ntaining
o ther info rmatio n abo ut a spec ific queue.

Chapter 19 ✦ Using M essage Queues

M SM QQuery

M SM QQueueInfosv

M SM QQueueInfo

M SM QQueueInfo

M SM QM essage

M SM QQueue

M SM QEvent

Figure 19-3: The Message Queuing Object Model

✦ MSMQQueue – is the base o bjec t in the o bjec t mo del. Yo u use this o bjec t to
ac c ess the individual messages in the queue.

✦ MSMQMessage – ho lds a message that is put in a queue o r rec eived fro m a
queue.

✦ MSMQEvent – is used to define queuing events in yo ur applic atio n. These
events are fired as info rmatio n arrives at yo ur applic atio n.
Note

M aking it simpler: To sim plify this discussion of m essage queues, I’m going to
focus on private queues, w hich m eans that I’m going to ignore the MSMQQuery
and MSMQQueueInfos objects. The only function lost by om itting the discussion
of these objects is the ability to dynam ically locate the proper queue by nam e
only. To access a private queue, you m ust know the its nam e as w ell as the com puter w here it exists.

To add message queuing to yo ur applic atio n, yo u need to selec t the Mic ro so ft
Message Queue 2.0 Objec t Library in the Referenc es dialo g bo x (see Figure 19-4).
To display this dialo g bo x, c ho o se Pro jec t ➪ Referenc es fro m the main menu.

407

408

Part IV ✦ COM + Transactions and M essage Queues

Figure 19-4: Selecting
the Microsoft Message
Queue Object Library

The M SM QQueueInfo Object
The MSMQQueueInfo o bjec t is used to c reate o r o pen a message queue. It c an also
set and return info rmatio n abo ut a partic ular queue.

M SM QQueueInfo object properties
Table 19-1 lists the pro perties o f the MQMQQueueInfo o bjec t.

Table 19-1
Properties of the M SM QQueueInfo Object
Property

Description

Authenticate

A Long value that specifies w hether the queue accepts
only authenticated m essages.

BasePriority

A Long that specifies a base priority for all m essages sent
to a public queue.

CreateTime

A Date value containing the date and tim e the public
queue w as created.

IsTransactional

A Boolean value w hen True m eans only m essages from
transactions w ill be accepted into the queue.

IsWorldReadable

A Boolean w hen True indicates that everyone can read
the m essages in the queue.

Chapter 19 ✦ Using M essage Queues

Property

Description

Journal

A Long w hen set to MQ_JOURNAL (0) m eans that the
m essages aren’t saved; MS_JOURNAL (1) m eans that
w hen a m essage is rem oved from the queue, it is stored
in the journal queue.

JournalQuota

A Long containing the size in kilobytes of the journal
queue.

Label

A String value containing up to 124 characters that
describe the queue.

ModifyTime

A Date value containing the date and tim e w hen the
properties of the queue w ere last m odified.

PathName

A String containing the path nam e of the queue. This
value is in the form of \system\queue or
\system\PRIVATE$\queue.

PathNameDNS

A String containing the path nam e of the queue, w here
the system nam e is fully qualified.

PrivLevel

A Long w hen set to MQ_PRIV_LEVEL_NONE (0) m eans
that the queue accepts only unencrypted m essages;
MQ_PRIV_LEVEL_OPTIONAL (1) m eans that the queue
doesn’t enforce privacy (default); or MQ_PRIV_LEVEL
_BODY (2) accepts only encrypted m essages.

QueueGuid

A String containing the GUID of the queue.

Quote

A Long containing the m axim um size of the queue in
kilobytes.

ServiceTypeGuid

A String containing the type of service provided by the
queue.

M SM QQueueInfo object methods
The MSMQQueueInfo o bjec t c o ntains metho ds fo r managing queues.

Sub Create ([IsTransactional], [IsWorldReadable])
The Create metho d c reates a new queue based o n the pro perties defined in this
o bjec t.

409

410

Part IV ✦ COM + Transactions and M essage Queues

IsTransactional is a Boolean when True means o nly messages fro m transac tio ns will be ac c epted into the queue.
IsWorldReadable is a Boolean when True indic ates that everyo ne c an read the
messages in the queue.

Sub Delete( )
The Delete metho d deletes the queue asso c iated with this o bjec t.

Function Open(Access As Long, ShareM ode As Long) As M SM QQueue
The Open metho d returns an o bjec t referenc e to MSMQQueue spec ified by the
PathName pro perty.

Access is a Long value spec ifying the level type o f ac c ess to the queue. Multiple values may be c o mbined by adding them to gether. Values are MQ_RECEIVE_ACCESS (1)
means that messages c an be rec eived o r peeked at in the queue; MQ_SEND_ACCESS
(2) means that messages c an be sent to the queue; and MQ_PEEK_ACCESS (32) means
that yo u c an peek at messages in the queue, but no t remo ve them.
ShareMode is a Long spec ifying ho w the queue is shared. A value o f MQ_DENY_NONE
(0) means that the queue is shared with everyo ne (yo u must use this value if yo u
spec ify MQ_SEND_ACCESS o r MQ_PEEK_ACCESS); o r MQ_DENY_RECEIVE_SHARE (1)
prevents anyo ne exc ept tho se in this pro c ess fro m ac c essing the queue (this value
sho uld be used when yo u spec ify MQ_RECEIVE_ACCESS).

Sub Refresh( )
The Refresh metho d gets a fresh c o py o f the pro perties asso c iated with this
queue.

Sub Update( )
The Update metho d updates the Ac tive Direc to ry fo r a public queue o r the lo c al
c o mputer with the c urrent pro perty values fo r this queue.

The M SM QQueue Object
The MSMQQueue o bjec t is a fundamental o bjec t when dealing with message queuing.
This o bjec t has the nec essary pro perties and metho ds to ac c ess the info rmatio n in
the queue. The MSMQQueueInfo o bjec t is used to o pen the queue and return an
o bjec t referenc e to this o bjec t.

Chapter 19 ✦ Using M essage Queues

M SM QQueue object properties
Table 19-2 lists the pro perties o f the MQMQQueue o bjec t.

Table 19-2
Properties of the M SM QQueue Object
Property

Description

Access

A Long value indicating w hether you can send m essages, peek at
m essages, or receive m essages from the queue.

Handle

A Long containing a handle of the open queue.

IsOpen

A Boolean value w hen True m eans that the queue is open.

QueueInfo

An object reference to a MSMQQueueInfo object containing
additional inform ation about the queue.

ShareMode

A Long that indicates w hether the queue is available to everyone or
w hether only this process.

M SM QQueue object methods
The MSMQQueue o bjec t c o ntains metho ds fo r examining the c o ntents o f the queue.

Sub Close( )
The Close metho d c lo ses the queue.

Sub EnableNotification(Event As M SM QEvent, [Cursor],
[ReceiveTimeout])
The EnableNotification metho d instruc ts the message queuing so ftware to trigger events using the MSMQEvent o bjec t. No te that this o bjec t needed to be dec lared
using the WithEvents keywo rd in o rder to rec eive the events. Yo u c an spec ify that
the event will be fired when there is a message in the queue, when a message is at
the queue’s c urrent lo c atio n, o r when a message is at the queue’s next lo c atio n.
No te that it may be po ssible that multiple messages may be in fro nt o f the message
that triggered the event.

Event is an o bjec t referenc e to an MSMQEvent o bjec t that has been dec lared
WithEvents, whic h will be fired as needed.

411

412

Part IV ✦ COM + Transactions and M essage Queues

Cursor is an enumerated type that spec ifies the ac tio n o f the c urso r. A value o f
MQMSG_FIRST (0) means that the event will be fired when a message is in the queue.
A value o f MQMSG_CURRENT (1) means that the event will be fired when a message is
at the c urrent lo c atio n o f the c urso r. A value o f MQMSG_NEXT (2) means that the
event will be fired when a message is at the new c urso r lo c atio n.
ReceiveTimeout is a Long c o ntaining the number o f millisec o nds that MSMQ will
wait fo r a message to arrive.

Function Peek([WantDestinationQueue], [WantBody], [ReceiveTimeout])
As M SM QM essage
The Peek metho d returns the first message in the queue witho ut rec eiving the message fro m the queue. If the queue is empty, it will wait fo r a message to arrive.

WantDestinationQueue is a Boolean when True means that the MSMQMessage.
DestinationQueueInfo pro perty will be updated to c o ntain the info rmatio n
abo ut the destinatio n queue. If no t spec ified, a value o f False will be assumed.
WantBody is a Boolean when True means that the bo dy o f the message sho uld be
returned (default). Set this value to False to reduc e the amo unt o f time to return
the message.
ReceiveTimeout is a Long c o ntaining the number o f millisec o nds that MSMQ will
wait fo r a message to arrive.

Function PeekCurrent([WantDestinationQueue], [WantBody],
[ReceiveTimeout], [WantConnectorType]) As M SM QM essage
The PeekCurrent metho d returns the c urrent message in the queue witho ut
rec eiving it.

WantDestinationQueue is a Boolean when True means that the MSMQMessage.
DestinationQueueInfo pro perty will be updated to c o ntain the info rmatio n
abo ut the destinatio n queue. If no t spec ified, a value o f False will be assumed.
WantBody is a Boolean when True means that the bo dy o f the message sho uld be
returned (default). Set this value to False to reduc e the amo unt o f time to return
the message.
ReceiveTimeout is a Long c o ntaining the number o f millisec o nds that MSMQ will
wait fo r a message to arrive.
WantConnecterType is a Boolean when True means that c o nnec to r info rmatio n
will also be retrieved. If no t spec ified, a value o f False will be assumed.

Chapter 19 ✦ Using M essage Queues

Function PeekNext([WantDestinationQueue], [WantBody],
[ReceiveTimeout], [WantConnectorType]) As M SM QM essage
The PeekNext metho d returns the next metho d in the queue witho ut rec eiving the
message.

WantDestinationQueue is a Boolean value when True means that the
MSMQMessage.DestinationQueueInfo pro perty will be updated to c o ntain the
info rmatio n abo ut the destinatio n queue. If no t spec ified, a value o f False will be
assumed.
WantBody is a Boolean when True means that the bo dy o f the message sho uld be
returned (default). Set this value to False to reduc e the amo unt o f time to return
the message.
ReceiveTimeout is a Long value c o ntaining the number o f millisec o nds that MSMQ
will wait fo r a message to arrive.
WantConnecterType is a Boolean when True means that c o nnec to r info rmatio n
will also be retrieved. If no t spec ified, a value o f False will be assumed.

Function Receive([Transaction], [WantDestinationQueue], [WantBody],
[ReceiveTimeout], [WantConnectorType]) As M SM QM essage
The Receive metho d returns the first message in the queue and remo ves it fro m
the queue.

Transaction is an MSMQTransaction o bjec t o r o ne o f these values: MQ_NO_
TRANSACTION (0), whic h means that c all is no t part o f a transac tio n; MQ_MTS_
TRANSACTION (1), whic h means that the c all is made as part o f the c urrent MTS
o r COM+ transac tio n; MQ_XA_TRANSACTION (2), whic h means that the c all is part
o f an externally c o o rdinated, XA-c o mpliant transac tio n; o r MQ_SINGLE_MESSAGE
(3), whic h means that the c all retrieves a single message.
WantDestinationQueue is a Boolean when True means that the MSMQMessage.
DestinationQueueInfo pro perty will be updated to c o ntain the info rmatio n abo ut
the destinatio n queue. If no t spec ified, a value o f False will be assumed.
WantBody is a Boolean when True means that the bo dy o f the message sho uld be
returned (default). Set this value to False to reduc e the amo unt o f time to return
the message.
ReceiveTimeout is a Long c o ntaining the number o f millisec o nds that MSMQ will
wait fo r a message to arrive.

413

414

Part IV ✦ COM + Transactions and M essage Queues

WantConnecterType is a Boolean when True means that c o nnec to r info rmatio n
will also be retrieved. If no t spec ified, a value o f False will be assumed.

Function ReceiveCurrent([Transaction], [WantDestinationQueue],
[WantBody], [ReceiveTimeout], [WantConnectorType]) As
M SM QM essage
The ReceiveCurrent metho d returns the c urrent message in the queue and
remo ves it fro m the queue.

Transaction is an MSMQTransaction o bjec t o r o ne o f these values: MQ_NO_
TRANSACTION (0), whic h means that c all is no t part o f a transac tio n; MQ_MTS_
TRANSACTION (1), whic h means that the c all is made as part o f the c urrent MTS
o r COM+ transac tio n; MQ_XA_TRANSACTION (2), whic h means that the c all is part
o f an externally c o o rdinated, XA-c o mpliant transac tio n; o r MQ_SINGLE_MESSAGE
(3), whic h means that the c all retrieves a single message.
WantDestinationQueue is a Boolean when True means that the MSMQ
Message.DestinationQueueInfo pro perty will be updated to c o ntain the
info rmatio n abo ut the destinatio n queue. If no t spec ified, a value o f False will
be assumed.
WantBody is a Boolean when True means that the bo dy o f the message sho uld be
returned (default). Set this value to False to reduc e the amo unt o f time to return
the message.
ReceiveTimeout is a Long c o ntaining the number o f millisec o nds that MSMQ will
wait fo r a message to arrive.
WantConnecterType is a Boolean when True means that c o nnec to r info rmatio n
will also be retrieved. If no t spec ified, a value o f False will be assumed.

Sub Reset( )
The Reset metho d mo ves to the c urrent message c urso r to the start o f the queue.

The M SM QM essage Object
The MSMQMessage o bjec t c o ntains the message that is sent and rec eived using
message queuing.

Chapter 19 ✦ Using M essage Queues

M SM QM essage object properties
Table 19-3 lists the pro perties o f the MSMQMessage o bjec t.
Caution

Set not for the body of a message: Don’t use the Set statem ent to assign an
object to the Body property of an MSMQMessage object. The Set statem ent creates a reference to an object. You should use an assignm ent statem ent to copy the
entire contents of the object into the Body property.

Table 19-3
Properties of the M SM QM essage Object
Property

Description

Ack

A Long value that specifies the type of
acknow ledgem ent that is returned.

AdminQueueInfo

An object reference to the MSMQQueueInfo
object that is used for acknow ledgem ent
m essages.

AppSpecific

A Long value containing application-specific
inform ation.

ArrivalTime

A Date value containing the date and tim e the
m essage arrived at the queue.

AuthenticationProviderName

A String value containing the nam e of the
cryptographic provider used to generate the
digital signature for the m essage.

AuthenticationProviderType

A Long value containing the type of the
cryptographic provider.

AuthLevel

A Long value that specifies w hether or not the
m essage should be authenticated w hen received.

Body

A Variant value containing the m essage to be
sent. Typically, this w ill be either a String or
apersistent COM com ponent.

BodyLength

A Long value containing the num ber of bytes in
the m essage.

Class

ALong value containing the type of m essage
being sent.
Continued

415

416

Part IV ✦ COM + Transactions and M essage Queues

Table 19-3 (continued)
Property

Description

ConnectorTypeGUID

A String value containing the GUID associated
w ith the com ponent that w as used to externally
set som e of the m essage properties that are
typically set by MSMQ.

CorrelationId

A Variant value containing a 20-byte
application-defined value that can be used to link
m essages together.

Delivery

Specifies how the m essage is delivered. Possible
values are MQMSG_DELIVERY_EXPRESS (0),
w hich is default and specifies a norm al delivery
process w here it m ay be possible to lose the
m essage in case of system failure; or MQMSG_
DELIVERY_RECOVERABLE (1), w hich m eans
that a m ore reliable system is used.

DestinationQueueInfo

An object reference to an MSMQQueueInfo
object that w ill be used as the destination queue.

DestinationSymmetricKey

A Variant value containing the sym m etric key
used to encrypt m essages.

EncryptAlgorithm

A Long value, w hich specifies the encryption
algorithm used to encrypt the body of the
m essage.

Extension

A Variant value containing additional
application-specific inform ation associated w ith
the m essage.

HashAlgorithm

A Long value containing the hash algorithm used
to authenticate a m essage.

Id

A Variant value containing the identifier for this
m essage. This value is autom atically generated by
MSMQ.

IsAuthenticated

An Integer value that specifies w hether the
local queue m anager authenticated the m essage.

IsFirstInTransaction

An Integer value that specifies w hether the
m essage is the first m essage sent in a
transaction.

IsLastInTransaction

An Integer value that specifies w hether
the m essage is the last m essage sent in a
transaction.

Chapter 19 ✦ Using M essage Queues

Property

Description

Journal

A Long value that specifies w hether a copy of the
m essage w as stored in the journal queue.

Label

A String value containing an applicationspecific value describing the m essage.

MaxTimeToReachQueue

A Long value containing the m axim um num ber
of seconds that can elapse before the m essage
m ust reach the queue before it w ill be canceled
and an error m essage returned to the sender.

MaxTimeToReceive

A Long value containing the m axim um num ber
of seconds that can elapse before the m essage
m ust be received before it w ill be canceled and
an error m essage returned to the sender.

MsgClass

A Long value containing the m essage type.

Priority

A Long value containing the relative priority of
the m essage.

PrivLevel

A Long value containing how the m essage is
encrypted.

ResponseQueueInfo

An object reference to an MSMQQueueInfo
object that specifies the response queue used to
send response inform ation.

SenderCertificate

A Byte() array containing the security certificate
inform ation.

SenderId

A Byte() array containing the nam e of the user
w ho sent the m essage.

SenderIdType

A Long value that specifies w hether the
SenderId value w as included in the m essage.

SenderVersion

A Long value containing inform ation about the
version of MSMQ that w as used to send the
m essage.

SendTime

A Date value containing the date and tim e the
m essage w as sent.

Signature

A Byte() containing the digital signature used
to authenticate the m essage.

SourceMachineGuid

A String array value containing the GUID of the
com puter, w hich sent the m essage.
Continued

417

418

Part IV ✦ COM + Transactions and M essage Queues

Table 19-3 (continued)
Property

Description

Trace

A Long value that specifies w here a m essage w ill
be returned to the sender in the report queue for
each hop taken by the m essage in the delivery
process.

TransactionId

A Byte() array that identifies the transaction
that sent the m essage.

TransactionStatusQueueInfo

An object reference to a transaction status queue
used for transactional m essages.

M SM QM essage object methods
The MSMQMessage o bjec t c o ntains metho ds fo r sending a message to a queue.

Sub AttachCurrentSecurityContext( )
The AttachCurrentSecurityContext metho d retrieves the sec urity info rmatio n
needed to attac h a c ertific ate to the message when requesting authentic atio n.

Sub Send(DestinationQueue As M SM QQueue, [Transaction])
The Send metho d transmits the message to the spec ified queue.

DestinationQueue is an o bjec t referenc e to an o pen MSMQQueue o bjec t.
Transaction is a Variant whic h c an be a referenc e to a MSMQTransaction o bjec t
o r o ne o f these c o nstants: MQ_NO_TRANSACTION (0), whic h means that this c all isn’t
part o f a transac tio n; MQ_MTS_TRANSACTION (1), whic h means that this c all is part o f
the c urrent MTS o r COM+ transac tio n; MQ_XA_TRANSACTION, whic h means that this
c all is part o f an externally c o o rdinated, XA-c o mpliant transac tio n; o r MQ_SINGLE_
TRANSACTION (3), whic h means the message c o mprises a single transac tio n.

M SM QEvent object events
The MSMQEvent o bjec t is used to define the events in yo ur pro gram that will be
fired when a message arrives in the queue. These events are defined by the
EnableNotification metho d o f the MSMQQueue o bjec t.

Chapter 19 ✦ Using M essage Queues

Event Arrived (Queue As Object, Cursor As Long)
The Arrived event is triggered when an MSMQMessage o bjec t arrives in the asso c iated queue.

Queue is an o bjec t referenc e to the queue c o ntaining the newly arrived message.
Cursor is a Long value fo r Cursor as spec ified in the EnableNotification
metho d.
Note

It’s not automatic: You m ust call the EnableNotification m ethod after processing the new ly arrived m essage in order to be notified w hen the next m essage
arrives.

Event ArrivedError (Queue As Object, ErrorCode As Long,
Cursor As Long)
The ArrivedError event is triggered when an erro r o c c urs.

Queue is an o bjec t referenc e to the queue c o ntaining the newly arrived message.
ErrorCode is a Long value c o ntaining the c ause o f the erro r.
Cursor is a Long value fo r Cursor as spec ified in the EnableNotification
metho d.
Note

Timeout for an error: The m ost com m on error returned in the ArrivedError event
is a tim eout, w here no m essages w ere received in the specified am ount of tim e.
As w ith the Arrived event, you m ust use the EnableNotification m ethod
again to receive the next event.

Accessing M essage Queues
While the o bjec t mo del fo r message queuing lo o ks c o mplic ated, it isn’t that diffic ult
to master, espec ially if yo u use private queues. To demo nstrate message queuing, I
built a pair o f pro grams. One o riginates requests, while the o ther respo nds to them.
The c lient pro gram (see Figure 19-5) retrieves info rmatio n abo ut a c usto mer, while
the server pro gram (see Figure 19-6) pro c esses the requests. I dec ided to use the
COM+ transac tio n to get the info rmatio n bec ause it demo nstrates ho w the vario us
piec es c an fit to gether into a ro bust applic atio n design.

419

420

Part IV ✦ COM + Transactions and M essage Queues

Figure 19-5: Running the m essage
queuing client

Figure 19-6: Running the m essage
queuing server

Building the client program
The c lient pro gram is a relatively simple Visual Basic pro gram that c o mmunic ates
with the server using two message queues. The first queue is the request queue,
whic h is used to pass info rmatio n to the server, while the sec o nd queue is the
respo nse queue, whic h is used to rec eive info rmatio n fro m the server.

Starting the client
When the c lient pro gram lo ads, I initialize bo th the request queue ( ReqQueue) and
the respo nse queue ( RespQueue) (see Listing 19-1). The pro c ess to o pen bo th
queues is the same. I c reate a new QueueInfo o bjec t, spec ify the PathName o f the
queue, and then use the Open metho d to get ac c ess to the queue.

Chapter 19 ✦ Using M essage Queues

Listing 19-1: The Form_Load event in M SM Q Client
Private Sub Form_Load()
Set ReqInfo = New MSMQQueueInfo
ReqInfo.PathName = “.\Private$\VB6DB19Req”
Set ReqQueue = ReqInfo.Open(MQ_SEND_ACCESS, MQ_DENY_NONE)
Set RespInfo = New MSMQQueueInfo
RespInfo.PathName = “.\Private$\VB6DB19Resp”
Set RespQueue = RespInfo.Open(MQ_RECEIVE_ACCESS, _
MQ_DENY_RECEIVE_SHARE)
Set RespEvent = New MSMQEvent
RespQueue.EnableNotification RespEvent, , 1000
End Sub

When I o pen the request queue, I spec ify MQ_DENY_NONE to allo w o ther pro grams to
share the request. Ho wever, when I o pen the respo nse queue, I do n’t permit anyo ne
else to rec eive data fro m it by spec ifying MQ_DENY_RECEIVE_SHARE. In general, eac h
user sho uld have their o wn unique respo nse queue. This permits the server to send
info rmatio n to multiple users, even tho ugh the users may no t be aro und to rec eive
the info rmatio n.
Onc e the respo nse queue is o pened, I c reate an MSMQEvent o bjec t, who se Arrived
event will be fired when a message arrives in the respo nse queue. I use the Enable
Notification metho d to asso c iate the Event o bjec t with the respo nse queue.
I also spec ify a timeo ut value o f 1000 millisec o nds (o r 1 sec o nd). If no messages
arrive in this amo unt o f time, the ArrivedError event will be fired.

Requesting a customer’s information
After the user enters a Custo merId value and presses the Get Custo mer butto n, the
Command1_Click event will be triggered (see Listing 19-2). This ro utine verifies that
a numeric value was entered into the Text1 text bo x, and then c o nstruc ts and
sends a message to the server.
I begin by c reating a new Customer o bjec t and assigning the value o f the text bo x
to the CustomerId pro perty. Then I c reate a new MSMQMessage o bjec t. I set the
ResponseQueueInfo pro perty to po int to the QueueInfo o bjec t asso c iated with
the respo nse queue.

421

422

Part IV ✦ COM + Transactions and M essage Queues

Listing 19-2: The Command1_Click event in M SM Q Client
Private Sub Command1_Click()
Dim msg As New MSMQMessage
If IsNumeric(Text1.Text) Then
Set c = New Customer
c.CustomerId = CLng(Text1.Text)
Set msg = New MSMQMessage
Set msg.ResponseQueueInfo = RespQueue.QueueInfo
msg.Body = c
msg.Send ReqQueue
End If
End Sub

The next statement is very c ritic al. Yo u must assign the o bjec t to the message’s
Body pro perty. This saves a c o py o f the o bjec t in the Body pro perty rather than
merely saving a po inter to the o bjec t. Onc e yo u’ve po pulated the message, yo u c an
use the Send metho d to plac e the message in a queue.
Caution

Set not: By now, if you see an assignm ent w ith an object on the right side of the
equal sign (= ), you expect to see a Set statem ent before the variable on the left
side. If you try to use the Set statem ent w ith the Body property of a m essage,
your inform ation w ill be lost as soon as the m essage is sent. Message queuing
saves the persistent inform ation from an object and then destroys it. The persistent inform ation is then sent to the destination, w here it is recreated w hen the
program receives the object.

Getting the results
Bec ause message queuing is async hro no us in nature, yo u do n’t kno w if the message
will be returned in millisec o nds, sec o nds, ho urs, o r days. Thus, it is useful fo r an
event to be fired when the message arrives. The Arrived event is triggered when a
message is ready to be rec eived (see Listing 19-3). If no messages arrive befo re the
timeo ut limit is reac hed, the ArrivedError event will be fired (see Listing 19-4).
The Arrived event begins by rec eiving the first message fro m the queue. The
queue that the message arrives in is spec ified by the Queue parameter and the
Receive metho d is used to retrieve the message. I spec ify a value o f 1000 millisec o nds to retrieve the message befo re returning an erro r.

Chapter 19 ✦ Using M essage Queues

Listing 19-3: The RespEvent_Arrived event in M SM Q Client
Private Sub RespEvent_Arrived(ByVal Queue As Object, _
ByVal Cursor As Long)
Dim r As Customer
Dim msg As MSMQMessage
Set msg = Queue.Receive(, , , 1000)
If Not (msg Is Nothing) Then
Set r = msg.Body
Text2.Text = r.Name
Text3.Text = r.Street
Text4.Text = r.City
Text5.Text = r.State
Text6.Text = FormatNumber(r.Zip, 0)
Text7.Text = r.Phone
Text8.Text = FormatDateTime(r.DateAdded, vbGeneralDate)
Text9.Text = FormatDateTime(r.DateUpdated, vbGeneralDate)
Check1.Value = CLng(r.MailingList) * -1
Text10.Text = r.Comments
End If
RespQueue.EnableNotification RespEvent, , 1000
End Sub

Onc e I have the message, it is a very simple matter to get a referenc e to the
Customer o bjec t fro m the Body pro perty and assign its values to eac h o f the fields
o n the fo rm.
Caution

What happened to all my requests?: When receiving m essages in the Arrived
event, it is possible to process the m essages too quickly. In this exam ple,
I assum ed that the user w ould subm it one request at a tim e, but there is nothing
to prevent the user from requesting inform ation on m ultiple custom ers before the
response to the first m essage is received. If this happens, it is quite possible that
the server w ill retrieve the next response before the user has finished view ing the
first response. In this case, it m ay be useful to save the m essages into a
Collection object as they are received. Another approach w ould be to exam ine
the inform ation in each response using the Peek m ethods, and only receive the
m essage from the m essage queue w hen you’re ready to delete it.

423

424

Part IV ✦ COM + Transactions and M essage Queues

Befo re I leave this event, I need to reset the trigger so that the next message is
rec eived. This is do ne using the same EnableNotification metho d that I o riginally used to enable this event.
Tip

But it worked once: If you can receive the first m essage, but your program doesn’t process any other m essages after that, verify that you re-enabled the response
event after processing a m essage.

The ArrivedError event is fired when a message do esn’t arrive in the message
queue befo re its timeo ut value. If yo u are expec ting a steady stream o f messages,
yo u may want to re-enable the event in the ArrivedError event (see Listing 19-4).

Listing 19-4: The RespEvent_ArrivedError event
in M SM Q Client
Private Sub RespEvent_ArrivedError(ByVal Queue As Object, _
ByVal ErrorCode As Long, ByVal Cursor As Long)
RespQueue.EnableNotification RespEvent, , 1000
End Sub

Building the server program
The server pro gram is designed to rec eive requests fro m a c lient in the request
queue, c all the GetCustomer transac tio n I wro te in Chapter 18, and return the data
to the c lient in the respo nse queue. It also inc ludes to o ls to c reate and delete the
queues that the c lient pro gram will use.

Creating queues
When the user presses the Build Queues butto n, the Command1_Click event will be
triggered (see Listing 19-5). Fo r eac h queue, this ro utine c reates a new QueueInfo
o bjec t, spec ifies the PathName o f the queue, and then c alls the Create metho d to
define the queue.
Tip

Deleting is simple: To delete a queue, use the sam e logic as show n in Listing 19-5,
but substitute Delete for Create.

Chapter 19 ✦ Using M essage Queues

Listing 19-5: The Command1_Click event in M SM Q Server
Private Sub Command1_Click()
Dim RespInfo As MSMQQueueInfo
Set RespInfo = New MSMQQueueInfo
RespInfo.PathName = “.\Private$\VB6DB19Resp”
RespInfo.Create
Set ReqInfo = New MSMQQueueInfo
ReqInfo.PathName = “.\Private$\VB6DB19Req”
ReqInfo.Create
Set respinfo = Nothing
Set ReqInfo = Nothing
End Sub

Starting the server
The server will no t pro c ess any messages until the user presses the Run Server butto n. This triggers the Command2_Click event, as sho wn in Listing 19-6. This ro utine
begins by writing that the server is ac tive to the text bo x o n the fo rm, and then it
o pens the request queue and enables no tific atio n using the ReqEvent o bjec t. At this
po int, the server will respo nd to messages as they are sent, using the ReqEvent_
Arrival events.

Listing 19-6: The Command2_Click event in M SM Q Server
Private Sub Command2_Click()
Text1.Text = FormatDateTime(Now, vbGeneralDate) & _
“ Server active.” & vbCrLf
Set ReqInfo = New MSMQQueueInfo
ReqInfo.PathName = “.\Private$\VB6DB19Req”
Set ReqQueue = ReqInfo.Open(MQ_RECEIVE_ACCESS,
MQ_DENY_RECEIVE_SHARE)
Set ReqEvent = New MSMQEvent
ReqQueue.EnableNotification ReqEvent, , 60000
End Sub

425

426

Part IV ✦ COM + Transactions and M essage Queues

Processing messages
The heart o f the server is the ReqEvent_Arrived event (see Listing 19-7). This
event is respo nsible fo r rec eiving the request, c alling the COM+ transac tio n, and
returning the data to the user via the respo nse queue. This ro utine begins by
appending an entry to the text bo x with the date and time that the message was
rec eived. This info rmatio n is useful in mo nito ring the server’s ac tivities while testing the pro gram, tho ugh it sho uld be eliminated in a pro duc tio n applic atio n.

Listing 19-7: The ReqEvent_Arrival event in