OpenVMS Notes: Installing MQSeries

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:

  1. first play around with the "Windows based" MQSeries server software
  2. then experiment with "Windows based" MQSeries client software connecting to the the "Windows based" MQSeries server software
  3. then finish up with the "OpenVMS based" MQSeries client software connecting to the the "Windows based" MQSeries server software
  4. Once this last step is ready to go, you will have little difficulty connecting to a different remote system
  5. Oops, due to some security restrictions introduced by IBM (required to connect to them via an Aventail VPN client which means a PC at our end), our OpenVMS system will FTP messages to/from a PC which will handle the MQ series stuff. Still need to do experiments with PCs though. 

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"

Menu

What is MQSeries?   
Quicker Beginnings Lab 1a Windows 2k (MQ Server) to Windows 2k (MQ Server)
Quicker Beginnings Lab 1b Windows ME (MQ Client) to Windows 2k (MQ Server)
Quicker Beginnings Lab 1c Windows 2k (MQ Client) to Windows 2k (MQ Server)
Quicker Beginnings Lab 2 OpenVMS    (MQ Client) to Windows 2k (MQ Server)
Client Environment Variables  Quick Reference (partial list)
Quicker Links Useful quick links at IBM
MS Visual Studio Tips Examples for use with Microsoft Visual Studio 6
... Building VB Clients   ''
... Building "C" Clients   ''
... Building C++ Exits   ''
... My MQSeries Application   ''
... Aventail Connect VPN Problems using Aventail Connect VPN Client

What is MQSeries? (What is 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:

  1. the sending system might delete a file (message) when the sender thinks the receiver has received the file
  2. the sending system might send multiple copies of a file to the receiver (over writing the originals)
  3. the sending system might send messages out of order

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:

Quicker Beginnings Lab #1a (Windows MQServer to MQServer)

verified using: Windows-2000 (MQ server) to Windows-2000 (MQ server)
  1. click here (2015): http://www.ibm.com/software/products/us/en/ibm-mq then click "Download Websphere MQ Trial"
  2. then download a 90 day evaluation copy of "MQSeries for Windows"
  3. perform a complete install on two different PCs
  4. bring up the "MQSeries First Steps" panel on each machine
  5. on machine #1, perform a "Default Configuration"
    1. always make this machine the first computer in the local repository
  6. on machine #2, perform a "Default Configuration"
    1. the first time through, make this machine the first computer in the local repository
    2. later on, try making this machine a member of a remote repository on the machine #1. To do this you will need to do the following
      1. run "MQSeries Explorer"
      2. stop the queue manager (right click on it then click on the STOP item)
      3. delete the queue manager (right click on it then click on the DELETE item)
      4. perform another "Default Configuration" from the "MQSeries First Steps" panel
  7. bring up MQSeries Postcard on machine #1; enter "one" when prompted for an "alias"
  8. bring up MQSeries Postcard on machine #2; enter "two" when prompted for an "alias"
  9. on machine #2, send a postcard to machine #1; the "MQSeries Postcard" application should receive it
  10. on machine #1, shut down "MQSeries Postcard"
  11. on machine #2, send a postcard to machine #1 (again)
  12. on machine #1, use "MQSeries Explorer" to view the contents of the postcard queue. You should see a message waiting there.

Quicker Beginnings Lab #1b (Windows MQClient to MQServer)

verified: Windows-ME (MQ client) to Windows-2000 (MQ server)

Basic Connectivity...

  1. click here (2015): http://www.ibm.com/software/products/us/en/ibm-mq then click "Download Websphere MQ Trial"
    then download a 90 day evaluation copy of "MQSeries for Windows" (a.k.a. Windows-NT5)
  2. Install it on a PC running Windows-NT or Windows-2000 (a.k.a. Windows-NT5)
  3. Perform a "Default Configuration"
    • always make this machine the first computer in the local repository
  4. Click here (2015): http://www.ibm.com/software/integration/wmq/clients/ to view/download client paks
  5. Install the client software on a second PC running any flavor of Windows-95/98/ME (I used Windows-ME).
    Note: If you intend to develop C/C++ code to interface with MQ, do yourself a favor and perform a CUSTOM install of the MQ client software then set the destination directory to folder C:\MQclient\
  6. If you logged into your client machine...
     
    1. then add the same user name to "Control Panel\Users and Passwords" on your server machine (server and client passwords do not need to match which seems kind of weird to me)

    If you didn't log into your client machine...
    ...then bring up an "MS-DOS Prompt"

    1. type: SET MQ_USER_ID = "Administrator"            (quotes are required to preserve case)
      Note: this parameter is not supported on client machines you are forced to log on to: OpenVMS, UNIX, Windows-NT, etc.
    2. type: SET MQ_PASSWORD ="what_ever_it_is"     (quotes are required to preserve case; Windows passwords are case sensitive)
      Note: this parameter is not supported on client machines you are forced to log on to: OpenVMS, UNIX, Windows-NT, etc.
    3. type: SET                                                                 (to view your environment variables)
       
  7. Bring up an MS-DOS prompt then locate the test executables...
    legend:
    <sr> system response
    <ur> user response
--------------------------
<sr>    C:\>
<ur>    CD C:\MQClient\Bin
<sr>    C:\mqclient\BIN>
<ur>    dir *.exe
  8. 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>    C:\mqclient\BIN>
<ur>    amqscnxc -?
<sr>    amqscnxc [-x ConnName [-c SvrconnChannelName]] [QMgrName]
    1. the "-x" switch specifies the I/P address of the other machine. Port 1414 is used by default
    2. Sample Note: source code file "amqscnxc.c" is found with "MQSeries for Windows-NT and Windows-2000" but not "MQSeries Client for Windows 95, 98 and Me - V5.2". You may want to peek at this file to learn how MQCONNX allows the client to connect without the use of environment variable MQSERVER or channel definition file "AMQCLCHL.TAB"
       
  9. This is an example of a good session...
    <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
  10. This is example #1 of a bad session:
    <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.
  11. This is example #2 of a bad session:
    <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"

Beyond Basic Connectivity...

Program Names

Most executable MQSeries demo programs follow this naming convention:

  1. amqsputb.exe (Application MQ String PUT from a BASIC source)
  2. amqsputc.exe (Application MQ String PUT from a C source)
  3. imqsputc.exe (Image MQ String PUT from a C++ source)

Setting up Windows environment variable: MQSERVER

  1. on the server machine, execute "c:\program files\mqseries\bin\runmqsc.exe" to access the MQSeries Command Interface
  2. now view all the currently defined channels by typing:

    DISPLAY CHANNEL(*)

    notice that one of them is SYSTEM.DEF.SVRCONN which we'll assume is the default server connection
     
  3. on the client machine, from an "MS-DOS" prompt, define an environmental variable using one of the channels just acquired like so:

    SET MQSERVER=SYSTEM.DEF.SVRCONN/TCP/192.168.1.220
     
  4. type: SET (to view your environment variables)
     
  5. This is an example of a good session:
    <sr>    C:\mqclient\BIN>
<ur>    amqsgetc default
<sr>    Sample AMQSGET0 start
        no more messages
        Sample AMQSGET0 end
  6. reason code 2059 means that you made a typo in the CHANNEL (first third) of the MQSERVER variable.
  7. reason code 2085 means that you made a typo in the queue name

Storing messages with demo program 'AMQSPUTC'

  1. on the server machine, execute "c:\program files\mqseries\bin\runmqsc.exe" to access the MQSeries Command Interface
  2. now view all the currently defined channels by typing:
    DISPLAY QMGR
    look for a parameter titled QMNAME (mine is 'QM_rieck2')
  3. This is an example of a good session:
    <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
  4. Use the GUI on the NT server machine to...
     
    1. non-destructively read the messages like so:
      <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
    2. destructively read the messages like so:
      <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'

  1. This is an example of a good session:
    <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
  2. Now run the program again and you should get this:
    <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

Quicker Beginnings Lab #1c (Windows MQClient to MQServer)

verified: Windows-2000 (MQ client) to Windows-2000 (MQ server)

  1. Click here (2015): http://www.ibm.com/software/products/us/en/ibm-mq
    then download a 90 day evaluation copy of MQSeries for Windows-NT and Windows-2000 (a.k.a. Windows-NT5)
  2. Install it on a PC running Windows-NT or Windows-2000 (a.k.a. Windows-NT5)
  3. Perform a "Default Configuration"
    1. always make this machine the first computer in the local repository
  4. Click here (2015): http://www.ibm.com/software/integration/wmq/clients/ to view/download client paks
  5. Install the client software on a second PC running any flavor of Windows-NT or Windows-2000 (a.k.a. Windows-NT5)
  6. the rest is similar to Quicker Quick Beginnings 1b except for two things...
     
    1. Under certain circumstances, user ID's on a Windows-NT client can be truncated to a length of 12 characters when sent through the MQSeries authorization process. If you're logged on to the Windows-NT MQ client machine as "Administrator" (which has a length of 13 characters ), then you'll need to create an account on the Windows-NT MQ server machine with a user ID of "Administrato" (which is 12 characters in length). Make sure this account has "MQM" privs, "Administrator" privs, or both.
      Note: this does not happen when using the Windows-95 MQ client on a Windows-2000 machine (which is probably not a good idea anyway)
       
    2. Make sure you execute programs from the correct directory because it is possible, although not desirable, to have several MQ client packages present on the same machine at the same time (I've seen this happen after Windows-ME was upgraded to Windows-2000, and also when the older Win-95 client is installed on a Windows-2000 machine after the Win-NT client was already present; Newer client installers always look for older software so this doesn't happen all the time).

      Programmers may wish to use a shorter path (for source headers, linker objects, etc.) so during an install or upgrade, it is probably a good idea to install the MQ client software in folder "C:\MQClient" rather than the default location. Note that the installation folder directory can always be changed when the installation mode is "Custom" rather than "Typical".

      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"

Quicker Beginnings Lab #2 (OpenVMS MQClient to Windows MQServer)

verified: OpenVMS-7.2-1 (MQ client) to Windows-2000 (MQ server)

  1. click here (2015): http://www.ibm.com/software/integration/wmq/clients/ to download client paks
  2. then download one of the client placks for your server (VAX, Alpha, Itanium, etc.)
    logon to OpenVMS as "SYSTEM" and install the software using DCL command: Product/Install
    Note: "IBM-AXPVMS-MQSERIES-V0202--1.PCSI" will only allow an installation by user: SYSTEM
  3. type: @MQS_LOGICALS.COM (to create the MQSeries logical names)
  4. be sure to add the line: "$@MQS_LOGICALS" to file: "SYS$MANAGER:SYSTARTUP_VMS.COM" so your logical names are created during subsequent reboots
  5. ignore file "MQS_SYMBOLS.COM" if you've only installed software for "MQSeries client"
  6. locate the test executables...
    legend:
    <sr> system response
    <ur> user response
----------------------------
<sr>    $
<ur>    SET DEF MQS_EXAMPLES
<sr>    $
<ur>    SET DEF [.BIN]
<sr>    $
<ur>    DIR *.EXE


  7. 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]
    1. the first user response creates a DCL foreign command so OpenVMS can pass command line args to "C" programs
    2. the "-x" switch specifies the I/P address of the other machine. Port 1414 is used by default
       
  8.   
    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


  9.   
    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
    1. You are not an authorized user on the other (server) machine.
    2. Check that "SYSTEM" (or what ever you are currently logged in as) is a valid user on your Windows-2000 machine.
    3. Check "Control Panel\Administrative Tools\Event Viewer\Application Log" for further hints.
    4. If you're going to write an "OpenVMS Server" process that will be doing MQSeries client calls to a remote server, then that process must be started with a username that has been defined on the remote server (and OpenVMS) making sure that it has access to group: "MQM"
    5. Alternatively, you could create a OpenVMS user called "MUSR_MQADMIN" and start the server process using that ID
    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"

Beyond Basic Connectivity...

Program Names

Most executable MQSeries demo programs follow this naming convention:

  1. amqsputb.exe (Application MQ String message PUT from a BASIC source)
  2. amqsputc.exe (Application MQ String message PUT from a C source)
  3. imqsputc.exe (Image MQ String message PUT from a C++ source)

Setting up the OpenVMS environment variable: MQSERVER

  1. on the server machine, execute "c:\program files\mqseries\bin\runmqsc.exe" to access the MQSeries Command Interface
  2. now view all the currently defined channels by typing:

    DISPLAY CHANNEL(*)

    notice that one of them is SYSTEM.DEF.SVRCONN which we'll assume is the default server connection
     
  3. on the client machine, from an OpenVMS prompt, define an environmental variable using one (or more) of the following examples:
     
    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"
     

  4. This is an example of a good session:
    <sr>    $
<ur>    amqsgetc "default" ! note that quotes are required to preserve lower case
<sr>    Sample AMQSGET0 start
        no more messages
        Sample AMQSGET0 end
  5. reason code 2059 means that you made a typo in the CHANNEL (first third) of the MQSERVER variable.
     
  6. reason code 2085 means that you made a typo in the queue name

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

(Some) Client Environmental Variables

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:

  1. 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.
  2. 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
  3. I have found that rewriting my program and replacing MQCONN with MQCONNX produced the best results

Quicker MQSeries Links (2006)

http://www.ibm.com/software/integration/wmq/library/index.html

Microsoft Visual Studio Tips (for Visual Studio neophytes)

Building MQ client programs using "Visual Basic 6"

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.

  1. double click on Visual Basic Project file: "C:\mqclient\TOOLS\vb\sampvb5\amqsgetb.vbp"
  2. menu "project", item  "Whatever properties" (usually the last item), tab "make", notice the "Conditional Compilation Arguments" text box:
    • it currently contains...
      "MqType=1" which forces your program to require library "MQM.DLL" (which you won't be able to find anywhere, including the Internet).
    • You should change the text box to ...
      "MqType=2" which will force your program to require "MQIC32.DLL".
      • The library for this file is in directory "C:\mqclient\TOOLS\lib"
      • The actual DLL is in "C:\mqclient\BIN"
        DLL Notes:
        1. required DLL files should be in the same directory as your executable, ...
          or "C:\Windows"
          or "C:\Windows\System"
          or "C:\Windows\System32"
        2. "MQIC32.DLL" won't load without "AMQCMEMA.DLL", "AMQRMQIA.DLL", "AMQXCS2.DLL", and "AMQZSAIC.DLL" so you can same some time now by moving them to your execution directory.
  3. you'll need to repeat this modification for every program in directory "C:\mqclient\TOOLS\vb\sampvb5\"

Building MQ client "C language" programs using "Microsoft Visual C++ 6"

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.

  1. start "Microsoft Visual C++ 6"
  2. click on menu "File", item "New", tab "Workspace", select "blank workspace", enter workspace name "whatever", select directory "c:\mqclient\TOOLS\C\samples", click "OK"
  3. click on menu "File", item "New", tab "Project", select "Win32 Console Application", enter project name "whatever", click "OK", select "An empty project", click "OK", click "OK"
  4. click on menu "Project", item "Add to project", sub item "Files", select "C:\mqclient\TOOLS\C\samples\amqsget0.c"
  5. click on menu "Project", item "Settings", select name "whatever" on the left hand side so that all tabs appear on the right
    1. click on tab "C/C++", category "Preprocessor", in text box "Additional Include Directories" enter "C:\mqclient\TOOLS\C\INCLUDE"
      • alternatively, in the program source file you can change this line:
        #include <cmqc.h>
        to this:
        #include "C:\mqclient\TOOLS\C\INCLUDE\cmqc.h"
    2. click on tab "Link"
      click on the "category" drop down menu then select "Input"
      click in the "Additional Library Path" text box and enter "C:\mqclient\TOOLS\lib" Click here for other possibilities.
    3. click on tab "Link"
      click on the "category" drop down menu then select "General"
      click in the "Object/Library Modules" text box then hit the "end" key (to get to the last item)
      now enter a space followed by "MQIC32.lib"
      which will cause your executable to attempt a run-time link to "MQIC32.dll" when it starts

Problems using Visual-C++ to build "Security Exits" and "Channel Exits"

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

My MQSeries Application

Under normal circumstances I would have used MQSeries client software on my OpenVMS machine and a CISCO router with built-in VPN support. However, my current application requires that I connect to another company using a proprietary non-standard VPN client which is only available on windows machines. This means that my OpenVMS platform will FTP messages into, and out of, my MQSeries Gateway which handles all the MQSeries Client and VPN stuff. 
Block Diagram Functions
  • Business Host
    • Will FTP messages into, and out of, the MQSeries Gateway
  • MQSeries Gateway
    • Production: A standalone MS-Visual-C application wakes up every minute to pass MQSeries messages to/from the remote customer (through a non standard VPN client)
    • Development: The same standalone MS-Visual-C application wakes up every minute to pass MQSeries messages to/from the local MQSeries Server
  • MQSeries Test Server
    • Development: During development and testing I used MQSeries client software on the OpenVMS machine to store test messages on the  MQSeries Server. These where picked up by the MQSeries Gateway which was "programmed" to use the MQSeries Server machine as a substitute for the Remote Company.
 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|
+-----------------+                             +-----------+  +-----------------+-+

"Aventail Connect" VPN

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
Neil Rieck
Waterloo, Ontario, Canada.