Reading IBM's MQSeries documentation is like reading the plans for an Interocitor (you feel like your trying to communicate with an extraterrestrial alien civilization). So unlike their "Quick Beginnings" manuals, this "Quicker Beginnings" web page should help you get up to speed faster. If you are building a solution where your mainframe or minicomputer will be acting as an MQ-client connecting to a remote MQ-server (as happened to me when I needed to build a link between "my server in Waterloo, Ontario" and "IBM's North American ticketing center in Lexington Kentucky"), I suggest you:
edit:
2015-11-30 what: fixed some dead links
note:
In an effort to confound all search engines, IBM has renamed "MQSeries" to "Websphere MQ"
The simplest answer is that it is "message queuing software" layered on top of various network communications protocols, the most important one being TCP/IP.
Prior to MQSeries, two systems might just FTP messages between themselves but the following problems could occur:
MQSeries messages sit in a queue (usually on the MQ server) and are not dequeued until a successful transfer and dequeue have been signaled by MQ software on the remote system. (makes you wonder if this is software was designed by a lawyer; "you de-queued the message so don't accuse me of loosing it"). MQSeries can also do EBCDIC to ASCII conversion.
EBCDIC-ASCII Examples:
verified using: Windows-2000 (MQ server) to Windows-2000 (MQ server)
verified: Windows-ME (MQ client) to Windows-2000 (MQ server)
Basic Connectivity...
If you didn't log into your client
machine...
...then bring up an "MS-DOS Prompt"
legend:
<sr> system response
<ur> user response
<sr> C:\> <ur> CD C:\MQClient\Bin <sr> C:\mqclient\BIN> <ur> dir *.exe
<sr> C:\mqclient\BIN> <ur> amqscnxc -? <sr> amqscnxc [-x ConnName [-c SvrconnChannelName]] [QMgrName]
<sr> C:\mqclient\BIN>
<ur> amqscnxc -x 192.168.1.220
<sr> Connecting to the default queue manager
using the server connection channel SYSTEM.DEF.SVRCONN
on connection name 192.168.1.220.
Connection established to queue manager QM_rieck2
Sample AMQSCNXC end
<sr> C:\mqclient\BIN>
<ur> amqscnxc
<sr> Connecting to the default queue manager
with no client information specified
MQCONNX ended with reason code 2058
Since no connection information was specified on the command line, you must use a TAB file.
See the bottom of error log file "C:\mqclient\ERRORS\AMQERR01.LOG" for more details.
<sr> C:\mqclient\BIN>
<ur> amqscnxc -x 192.168.1.220 yada
<sr> Connecting to the queue manager yada
using the server connection channel SYSTEM.DEF.SVRCONN
on connection name 192.168.1.220.
MQCONNX ended with reason code 2058
| MQSeries Reason Codes |
MQSeries Reason Text |
|---|---|
| 2035 | You are not an authorized user on the
other (server) machine. Check "Control Panel\Administrative Tools\Event Viewer\Application Log" for hints. Does your user have MQM group access on the server machine? |
| 2058 | Queue manager name not valid or not known. |
| 2059 | Queue manager not available for connection. |
| 2085 | Unknown object name |
| other API reason codes |
(2003)
http://www.ibm.com/software/ts/mqseries/library/manuals/csqfao/CSQFAO1P.HTM (2006) http://www.ibm.com/software/integration/wmq/library/index.html then click: "Application Programming Reference" |
| other help | check file "C:\mqclient\ERRORS\AMQERR01.LOG" |
Program Names
Most executable MQSeries demo programs follow this naming convention:
- amqsputb.exe (Application MQ String PUT from a BASIC source)
- amqsputc.exe (Application MQ String PUT from a C source)
- imqsputc.exe (Image MQ String PUT from a C++ source)
Setting up Windows environment variable: MQSERVER
<sr> C:\mqclient\BIN>
<ur> amqsgetc default
<sr> Sample AMQSGET0 start
no more messages
Sample AMQSGET0 end
Storing messages with demo program 'AMQSPUTC'
<sr> C:\mqclient\BIN>
<ur> amqsputc default QM_rieck2
<sr> Sample AMQSPUT0 start
target queue is default
<ur> this is data line 1 <enter>
<ur> this is data line 2 <enter>
<ur> this is data line 3 <enter>
<ur> <--- now just hit <enter> one more time to signal that we're finished
<sr> Sample AMQSPUT0 end
<ur> Start>Programs>IBM MQSeries>MQSeries Explorer <ur> Open Queue Manager: QM_rieck2 (or whatever your queue manager is named) <ur> Open Folder: Queues <ur> Open Queue: default
<ur> Start>Programs>IBM MQSeries>MQSeries First Steps <ur> Select Item: API Exerciser <ur> Connect to the desired queue manager using MQCONN or MQCONNX <ur> Open the desired queue using MQOPEN <ur> Now click MQGET until you run out of messages <ur> Now click MQCLOSE <ur> Now click MQDISC
Retrieving a message with demo program 'AMQSGETC'
<sr> C:\mqclient\BIN>
<ur> amqsgetc default
<sr> Sample AMQSGET0 start
message <this is data line 1>
message <this is data line 2>
message <this is data line 3>
no more messages
Sample AMQSGET0 end
<sr> C:\mqclient\BIN>
<ur> amqsgetc default<sr> Sample AMQSGET0 start
no more messages
Sample AMQSGET0 end
Example Program Summary
command function need environment variable
or channel definition
file "AMQCLCHL.TAB"?>amqscnxc -x 192.168.1.200 tests basic connectivity using MQCONNX n >amqsputc default string message put y >amqsgbrc default message browse y >amqsgets default string message get y >amqsprmc -q default -i yada.txt -t FLATFILE reference message (file) put y
verified: Windows-2000 (MQ client) to Windows-2000 (MQ server)
| MQSeries Client Package | Default Installation Directory (after a new install) |
Desirable Destination Directory for use by programmers |
|---|---|---|
| V 5.2 for Windows-95/98/ME | "C:\MQClient" | "C:\MQClient" |
| V 5.2 for Windows-NT/2000 | "C:\program files\mqclient software\" | "C:\MQClient" |
| V 5.3 for Windows-NT/2000 | "C:\program files\ibm\WebSphere MQ\" | "C:\MQClient" |
verified: OpenVMS-7.2-1 (MQ client) to Windows-2000 (MQ server)
legend:
<sr> system response
<ur> user response<sr> $ <ur> SET DEF MQS_EXAMPLES <sr> $ <ur> SET DEF [.BIN] <sr> $ <ur> DIR *.EXE
Program "amqscnxc.exe" is used to test general "client -> server" connectivity (and also demos the use of the new MQCONNX call). View this program's command line arguments like so... <sr> $ <ur> AMQSCNXC :== $SYS$COMMON:[SYSHLP.EXAMPLES.MQSERIES.BIN]AMQSCNXC.EXE <sr> $ <ur> amqscnxc -? <sr> amqscnxc [-x ConnName [-c SvrconnChannelName]] [QMgrName]
This is an example of a good session (note that "$" is the OpenVMS prompt):
<sr> $
<ur> amqscnxc -x 192.168.1.220 "default" ! double quotes to preserve case<sr> Connecting to the default queue manager
using the server connection channel SYSTEM.DEF.SVRCONN
on connection name 192.168.1.220.
Connection established to queue manager QM_rieck2
Sample AMQSCNXC end
This is an example of a bad session (note that '$' is the OpenVMS prompt): <sr> $ <ur> amqscnxc -x 192.168.1.220 yada ! no double quotes<sr> Connecting to the queue manager YADA <-- notice how we're suddenly using upper case using the server connection channel SYSTEM.DEF.SVRCONN on connection name 192.168.1.220. MQCONNX ended with reason code 2058
| MQSeries Reason Codes |
MQSeries Reason Text |
|---|---|
| 2035 |
|
| 2058 | Queue manager name not valid or not known. |
| 2059 | Queue manager not available for connection. |
| 2085 | Unknown object name |
| other API reason codes | (2003)
http://www.ibm.com/software/ts/mqseries/library/manuals/csqfao/CSQFAO1P.HTM (2006) http://www.ibm.com/software/integration/wmq/library/index.html then click: "Application Programming Reference" |
| other help | read files "MQS_ROOT:[MQM.ERRORS]*.log" |
Program Names
Most executable MQSeries demo programs follow this naming convention:
- amqsputb.exe (Application MQ String message PUT from a BASIC source)
- amqsputc.exe (Application MQ String message PUT from a C source)
- imqsputc.exe (Image MQ String message PUT from a C++ source)
Setting up the OpenVMS environment variable: MQSERVER
| DCL command | Variable Type | Scope |
|---|---|---|
| $MQSERVER == "SYSTEM.DEF.SVRCONN/TCP/192.168.1.220" | DCL symbol | only affects current process |
| $define MQSERVER "SYSTEM.DEF.SVRCONN/TCP/192.168.1.220" | "process level" logical name | only affects current process |
| $define/sys MQSERVER "SYSTEM.DEF.SVRCONN/TCP/192.168.1.220" | "system level" logical name | affects all processes |
Warning: ignore all IBM documentation
displaying a format using square brackets instead of slashes.
For example, this string will not work:
"SYSTEM.DEF.SVRCONN [TCP] 192.168.1.220"
<sr> $ <ur> amqsgetc "default" ! note that quotes are required to preserve lower case <sr> Sample AMQSGET0 start no more messages Sample AMQSGET0 end
Example Program Summary (use quotes in OpenVMS to preserve desired case)
command function requires an
environment variable
or channel definition
file "AMQCLCHL.TAB"?$amqscnxc -x 192.168.1.200 tests basic connectivity using MQCONNX n $amqsputc "default" string message put y $amqsgbrc "default" message browse y $amqsgets "default" string message get y $amqsprmc -q "default" -i yada.txt -t FLATFILE reference message (file) put y
Variable Notes Links MQSERVER Overrides the need for TAB file AMQCLCHL.TAB (2003) MQSeries Client Manual (Chapter 9) MQCHLLIB points to location of AMQCLCHL.TAB MQCHLTAB defines a new AMQCLCHL.TAB MQ_USER_ID required if the client machine doesn't know your user name MQ_PASSWORD required if the client machine doesn't know your user name Notes:
- It is possible to build a Windows based MQSeries client solution using MQSERVER. However, the program would have limited in flexibility since the MQSeries DLLs can't see changes made to environmental variable MQSERVER, via the "RegSetValueEx()" Windows function, without a reboot.
- The officially undocumented nature of AMQCLCHL.TAB makes me somewhat nervous since I'm not in total control. However, a hacked (uh, reverse engineered) overview can be found here: University of Winnipeg
- I have found that rewriting my program and replacing MQCONN with MQCONNX produced the best results
http://www.ibm.com/software/integration/wmq/library/index.html
Note: these instructions assume MQSeries client files were installed in directory "C:\MQclient\". If you didn't do this then your include paths are going to be ridiculously long.
Note: these instructions assume you're linking to Windows-95 MQ client files which are installed in directory "C:\mqclient\". If you didn't do this then your include paths are going to be ridiculously long. Click here for other possibilities.
On the Windows platform, "Security Exits" and "Channel Exits" are implemented as DLL files which are called by the MQ interface. Most IBM documentation states that these programs need to be written in "C" but C++ can also be used. However, very little IBM documentation states that an extern "C" prefix is required to disable "name mangling" of symbols exported by C++.
When I wrote a "C++ based" DLL not using the extern "C" prefix, I noticed that file "C:\mqclient\ERRORS\AMQERR01.LOG" contained the following error:
AMQ9539: User exit not valid
Explanation: Channel program "YADA.TEST" ended because user exit "ecisec(SecurityExit)" is not valid.
User action: Ensure that the user exit is specified correctly in the channel definition, and that the user exit program is correct and available.
In this case, the channel definition file "AMQCLCHL.TAB" was telling the MQ interface to look for an entry point named "SecurityExit" in DLL program "ecisec.dll" but the interface couldn't find it because C++ mangled names had been written to that DLL's symbol table. (name mangling is the method that C++ uses to enforce "type checking" etc.)
Example Declarations:IBM Visual Age C++ Code Stub: extern void MQENTRY _Export SecurityExit( ...Which translates to: extern void __cdecl _Export SecurityExit( ...Microsoft Visual Studio Equivalent: extern "C" __declspec(dllexport) void SecurityExit( ...Link: "DLL Examples" for novice Windows programmers
Block Diagram Functions
Business Host MQSeries Gateway PC +-------------------+ +-----------------+-+ +----------+ +-+-----------------+ | OpenVMS | | Windows-2000 |V| | LinkSys | |V| Remote Company | | Alpha Server DS20 +--+--+ MS-Visual-C App |P+---+ BEFSR41 +---> Internet <---+P| | | FTP | | | MQSeries Client |N| | Firewall | |N| MQSeries Server | +-------------------+ | +-----------------+-+ +----------+ +-+-----------------+ | | MQSeries Server PC | +-----------------+ | | Windows-2000 | Intranet <--+--+ MQSeries Server | | (dvlp use only) | +-----------------+
Final "Super-Secure" Block Diagram (to satisfy corporate security)
Business Host +-------------------+ +----------------+ +-+-----------------+ | OpenVMS | | Corporate | |V| Remote Company | | Alpha Server DS20 +--+--+ Firewall +----> Internet <---+P| | | FTP | | | in DMZ | |N| MQSeries Server | +-------------------+ | +----------------+ ^ +-+-----------------+ | | MQSeries Server | | MQSeries Gateway PC +-----------------+ | +-----+-----+ +-----------------+-+ | Windows-2000 | | | LinkSys | | Windows-2000 |V| | MQSeries Server +----+---> Intranet | BEFSR41 +--+ MS-Visual-C App |P| | (dvlp use only) | | Firewall | | MQSeries Client |N| +-----------------+ +-----------+ +-----------------+-+
After actually using (rather than just starting) the Aventail Connect VPN client version 3.23 S on Windows-2000, some time through the night you'll get a "GPF error" from program svchost.exe with a reference to aslsp.dll. Even though the following link refers to Aventail Connect version 4.12 on Windows-XP, it should shed some light on the situation...
http://support.aventail.com/akb/article01049.html
So it looks like we've got a conflict with another LSP (Layered Service Provider) feature called "Windows Fax Service". Disabling the fax service won't help but the following solution is better than the one described in Aventail article:
click Start>Programs>Aventail Connect>Config Tool
click tab "Advanced"
click radio dial "Secure only applications listed"
click button "Modify List"
type the name of the applications you wish to be intercepted by the Aventail VPN Client.
Note that it doesn't hurt to add a few others like telnet.exe which could be used in the initial testing of VPN connections.
Back
to Home