Running Sample Applications MSMQ includes the following sample applications: MSMQTest MQTestOA MQTrans Distributed Draw MSMQ API Test These applications can be used to test and demonstrate MSMQ functionality, as well as learn and experiment with the MSMQ APIs. MSMQTest is installed by default. Distributed Draw and MSMQ API Test are installed when you install the MSMQ SDK. Both Distributed Draw and MSMQ API Test can be run from the Start menu. When you install the MSMQ SDK, source files for all sample applications are installed. ======== MSMQTest ======== MSMQTest demonstrates basic MSMQ functionality in a complete C program, including usage of Queue and Message properties and many of the MSMQ APIs. The single source file, Msmqtest.c, contains the entire program. MSMQTest sends messages between two or more computers, or between two instances of MSMQTest on the same computer. MSMQTest can be run either as a receiving application (using the -r parameter) or as a sending application (using the -s parameter). You can run multiple instances of the application in sending or receiving mode. All messages you send from an instance of MSMQTest are sent to all the MSMQTest queues created by computers running MSMQTest in receiving mode. Similarly, computers running MSMQTest in receiving mode receive messages from all instances of MSMQTest in sending mode. The following procedure introduces MSMQTest, demonstrating how you can use it to observer basic message queuing functionality. To use MSMQTest: 1. Run two instances of the Windows NT command prompt or the Windows 95 MS-DOS prompt, either on one computer or two different computers. If you use two different computers, they must belong to the same site. 2. In each instance, change to the MSMQ directory (c:\program files\msmq by default). 3. In one instance, type msmqtest -r and then press ENTER to start MSMQTest in receive mode. If you run MSMQ Explorer, you see a msmqtest queue has been created on the computer you are using. The queue has no messages. 4. In the other instance, start the MSMQTest in send mode by typing msmqtest -s, and then pressing ENTER. 5. At the 'Enter a string:' prompt, type some text (for example, Hello World) and then press ENTER. The messages appear in the receiver's command prompt window. If you look at the msmqtest queue in MSMQ Explorer, you see it still has no messages. Because they have all been received by the receiving application, they do not appear in the queue. 6. In the command prompt window running MSMQTest in receiving mode, press CTRL+C. 7. In the MSMQTest sending window, type some additional messages. If you look at the msmqtest queue in MSMQ Explorer, you see the messages the sending application has sent, but that MSMQ has not yet been able to deliver as the receiving application is no longer running. 8. Restart MSMQTest in receiving mode by typing msmqtest -r, and then pressing ENTER. The messages stored by MSMQ are immediately delivered to the receiving application. If you switch to MSMQ Explorer and press F5 to refresh the display, you see that the queue has no messages because they have all been read by the receiving application. 9. In the MSMQTest sending window, type quit in lower case, and then press ENTER. If you switch to MSMQ Explorer and press F5 to refresh the display, you see that the queue has been deleted. If you exit the sending application by pressing CTRL+C, the queue is not deleted. The queue is deleted only when you exit the sending application by typing quit in lower case, and then pressing ENTER. If you exit the sending application while there are undelivered messages in the receiving application queue, the queue is not removed. However, if you run the receiving application again, it empties the queue (displaying each message), removes the queue, and then exits. ======== MQTestOA ======== MQTestOA offers the exact same functionality as the above MSMQTEST sample application, but it is written on top of the ActiveX programming model. By looking at this application, you will see how to use the ActiveX programming model from C++. ======= MQTrans ======= The MQTRANS sample demonstrates the transactional features of the MSMQ product. The sample uses both transactional messaging (provided by Microsoft MSMQ) and database transactions (provided by Microsoft SQL Server version 6.5). It emulates two bank accounts: one on the receiving side, with an initial sum of $500 and the other on the sending side with an initial sum of $1000. The sender can transfer money to the receiver as long as his balance is positive. Trying to transfer money when the sender balance is negative will abort the transaction. Before running the sample for the first time you have to 1. Create a database in SQL server (Run SQL Enterprise Manager) 2. Define an ODBC data source named "MSMQDemo", which points to the database. (Run ODBC Control Panel Applet) To run the sample: receiver side- run 'mqtrans -r' sender side- run 'mqtrans -s' and follow the instructions. To build the sample: Edit the makefile and update C_INCLUDE to point to your compiler/sdk include directory. Then run 'nmake'. ================ Distributed Draw ================ Distributed Draw (Disdraw.exe) is a scratch pad-like application that allows you to draw lines and type text in the local and remote application. When you provide the name of a destination queue, MSMQ sends the drawings and text to another instance of Distributed Draw. Two versions of Distributed Draw are installed with the MSMQ SDK: one built using the MSMQ APIs, the other built using the MSMQ ActiveX controls. You can send and receive messages between the two different versions. Both versions of Distributed Draw use most of the basic MSMQ functions. To see MSMQ functionality using Distributed Draw: 1. Run Distributed Draw. 2. Type your name in the Name. The name you specify is used to create a queue on your computer. 3. Run Distributed Draw on a second computer, specifying a different name. This computer must be in the same site as the first computer. 4. In Remote Friend on the second computer, type the name you used in step 2. The Attach button is no longer available after Distributed Draw has opened the queue. 5. In Remote Friend on the first computer, type the name you used in step 3. Both instances of Distributed Draw now have their own queue for receiving messages, and have opened the other instance's queue for send. As you type text or draw objects, each character and mouse movement is sent between the two instances of Distributed Draw. You can close either instance of Distributed Draw and continue sending messages. When Distributed Draw is restarted and you use the same name, Distributed Draw receives all undelivered messages. If you change the deliver method from Express to Recoverable, you can close one instance of Distributed Draw, restart the computer, restart Distributed Draw, and receive messages that were sent while the computer was rebooting. Tip To clear the Distributed Draw display drawing area, right-click within the drawing area. ============= MSMQ API Test ============= MSMQ API Test (Mqapitst.exe) can be used to test and experiment with MSMQ. Using Mqapitst.exe you can run the following API calls: - MQCreateQueue - MQDeleteQueue - MQOpenQueue - MQCloseQueue - MQSendMessage - MQReceiveMessage - MQLocate (MQLocate calls the three locate APIs: MQLocateBegin, MQLocateNext, and MQLocateEnd) Note Before you can open a queue using Mqapitst.exe, you must use MQLocate to located the queue. Mqapitst.exe locates queues based on their labels. Also, if you are using one instance of Mqapitst.exe, you cannot send messages to and receive messages from the same queue without first closing the queue handle. For example, if you open the queue for send and send five messages, you cannot read the messages without first closing your handle to the queue, and then opening the queue for read. The main source file for the program, where the menus are invoked and the MSMQ APIs are called, is Mainfrm.cpp. When building Mqapitst on Windows 95, only ANSI configurations should be used. For more information, see the MSMQ SDK help file. The following procedure shows you how to use MSMQ API Test to become familiar with and experiment with the MSMQ APIs. To see MSMQ functionality using MSMQ API Test: 1. Run two instances of MSMQ API Test (Mqapitst.exe), either on one computer, or two different computers. 2. Create a queue in one application, entering the Pathname (for example, "YourMachine\MyQueue") and the Label (for example, "MQ API Test") of the queue. 3. Locate the queue in the other instance of MSMQ API Test. You can do this by using the MQLocate API to search for the queue's label. 4. In one instance of MSMQ API Test open the queue for Send. 5. In the other MSMQ API Test open the queue for Receive. 6. Send and Receive messages between the applications. Experiment with the various send options, such as message priority, message time-to-reach-queue, time-to-be-received, acknowledgements, and delivery modes. 7. Close and then delete the queues.