Preparing and running the sample programs

 

The following sections help you find the samples that you need to run on the different platforms.

 

OS/400

The source for WebSphere MQ for iSeries sample programs are provided in library QMQMSAMP as members of QCSRC, QCLSRC, QCBLSRC, QCBLLESRC, QRPGSRC, and QRPGLESRC. To run the samples use either the C executable versions, supplied in the library QMQM, or compile them as you would any other WebSphere MQ application. For more information see Running the sample programs.

 

UNIX systems


Table 39. Where to find the samples for WebSphere MQ on UNIX systems

Content Directory
source files /opt/mqm/samp
C source file for Windows 3.1 sample /opt/mqm/win_client/samp
dead-letter queue handler source files /opt/mqm/samp/dlq
executable files /opt/mqm/samp/bin
Other WebSphere MQ client executable files /opt/mqm/dos_client/samp/bin /opt/mqm/os2_client/samp/bin /opt/mqm/win_client/samp/bin

Note:
For WebSphere MQ for AIX opt/mqm is usr/mqm, for WebSphere MQ for other UNIX systems opt/mqm is opt/mqm.

The WebSphere MQ on UNIX systems sample files will be in the directories listed in Table 39 if the defaults were used at installation time. To run the samples, either use the executable versions supplied or compile the source versions as you would any other applications, using an ANSI compiler. For information on how to do this, see Running the sample programs.

 

Compaq OpenVMS Alpha


Table 40. Where to find the samples for MQSeries for Compaq OpenVMS Alpha

Content Directory
source files MQS_EXAMPLES
C source file for Windows 3.1 sample [.WIN_CLIENT.SAMP] under MQS_EXAMPLES
dead-letter queue handler source files [.DLQ] under MQS_EXAMPLES
executable files [.BIN] under MQS_EXAMPLES
Other WebSphere MQ client executable files [.DOS_CLIENT.SAMP.BIN] under MQS_EXAMPLES [OS2_CLIENT.SAMP.BIN] under MQS_EXAMPLES [WIN_CLIENT.SAMP.BIN] under MQS_EXAMPLES

The MQSeries for Compaq OpenVMS Alpha sample files are in the directories listed in Table 40 if the defaults were used at installation time. To run the samples, either use the executable versions supplied or compile the source versions as you would any other applications, using an ANSI compiler. For information on how to do this, see Running the sample programs.

 

OS/2 and Windows systems


Table 41. Where to find the samples for MQSeries for OS/2 Warp and WebSphere MQ for Windows

Content Directory
C source code <drive:directory>\MQM\TOOLS\C\SAMPLES
<drive:directory>\Program Files\IBM\WebSphere MQ\
Tools\C\Samples
Source code for dead-letter handler sample <drive:directory>\MQM\TOOLS\C\SAMPLES\DLQ
<drive:directory>\Program Files\IBM\WebSphere MQ\
Tools\C\Samples\DLQ
C source code for Windows 3.1 sample <drive:directory>\MQM\WIN
COBOL source code <drive:directory>\MQM\TOOLS\COBOL\SAMPLES
<drive:directory>\Program Files\IBM\WebSphere MQ\
Tools\Cobol\Samples
C executable files <drive:directory>\MQM\TOOLS\C\SAMPLES\BIN
<drive:directory>\Program Files\IBM\WebSphere MQ\
Tools\C\Samples\Bin
Other WebSphere MQ client executable files <drive:directory>\MQM\DOS
<drive:directory>\MQM\AIX
<drive:directory>\MQM\WIN
Sample MQSC files <drive:directory>\MQM\TOOLS\MQSC\SAMPLES
<drive:directory>\Program Files\IBM\WebSphere MQ\
Tools\MQSC\Samples
PL/I source code <drive:directory>\MQM\TOOLS\PLI\SAMPLES
<drive:directory>\Program Files\IBM\WebSphere MQ\
Tools\PLI\Samples
Visual Basic Version 6 source code <drive:directory>\Program Files\IBM\WebSphere MQ\
Tools\VB\SampVB6

Notes:

  1. The Visual Basic samples are not available for OS/2.

  2. Paths beginning "<drive:directory>\Program Files\" apply to Windows systems; paths beginning "<drive:directory>\MQM\" apply to OS/2.

The MQSeries for OS/2 Warp and WebSphere MQ for Windows sample files will be in the directories listed in Table 41 if the defaults were used at installation time, the <drive:directory> will default to <c:>. To run the samples, either use the executable versions supplied or compile the source versions as you would any other MQSeries for OS/2 Warp or WebSphere MQ for Windows applications. For information on how to do this, see Running the sample programs.

 

Compaq NonStop Kernel

This section tells you how to build the MQSeries for Compaq NonStop Kernel sample programs:

 

Building C sample programs

 

Non-native (using non-native static library MQMLIB)

The subvolume ZMQSSMPL contains the following TACL macro files for building non-native sample C applications:

CSAMP
Usage: CSAMP source-code-file-name

This is a basic macro for compiling a C source file using the include files contained in subvolume ZMQSLIB. For example, to compile the sample AMQSBCG0, use CSAMP AMQSBCG0. If the compilation is successful, the macro produces an object file with the last character of the file name replaced by the letter O; for example, AMQSBCGO.

BSAMP
Usage: BSAMP exe-file-name

This is a basic macro used to bind an object file with the user library MQMLIB in ZMQSLIB. For example, to bind the compiled sample AMQSBCG0, use BSAMP AMQSBCG. The macro produces an executable file called exe-file-nameE; for example, AMQSBCGE.

COMPALL
Usage: COMPALL

This TACL macro compiles each of the sample source code files using the CSAMP macro.

BINDALL
Usage: BINDALL

This TACL macro binds each of the sample object files into executables using the BSAMP macro.

BUILDC
Usage: BUILDC

This TACL macro compiles and binds all of the C sample files using the macros COMPALL and BINDALL.

 

Native (using native static library MQMLIBN)

For a native install, use the following TACL macro files to build sample MQI applications:

NMCALL
Usage: NMCALL

Macro to compile all samples native using NMCSAMP.

NMCSAMP
Usage: NMCSAMP source-code-file-name

This is a basic macro for compiling a C source file using the include files contained in subvolume ZMQSLIB. For example, to compile the sample AMQSBCG0, use NMCSAMP AMQSBCG0. If the compilation is successful, the macro produces an object file with the last character of the file name replaced by the letter O; for example, AMQSBCGO.

NMLDSAMP
Usage: NMLDSAMP exe-file-name

This basic macro links an object file with the static native MQI library MQMLIBN in ZMQSLIB.

NMLDALL
Usage: NMLDALL

This TACL macro binds each of the sample object files into executables using the NMLDSAMP macro.

NMBUILDC
Usage: NMBUILDC

This TACL macro compiles and binds all the native C sample files using the macros NMCALL and NMLDALL.

 

Native (using SRL MQSRLLIB)

NMLDSSMP
Usage: NMLDSSMP exe-file-name

This basic macro links an object file with the native MQ SRL MQSRLLIB in ZMQSLIB.

NMLDSALL
Usage: NMLDSALL

This TACL macro binds each of the sample object files into executables using the NMLDSSMP macro.

NMBULDSC
Usage: NMBULDSC

This TACL macro compiles and binds all of the Native C sample files using the macros NMCALL and NMLDSALL.

NMLDPSRL
Usage: NMLDPSRL exe-file-name

This basic macro links an object file with the MQSeries private SRL in ZMQSLIB

NMCPSRL
Usage: NMCPSRL source-code-file-name

Macro to compile user code for inclusion in the MQSeries PSRL.

NMLDUSRL
Usage: NMLDUSRL object-input-file, where object-input-file is a file containing a list of objects to be linked.

This is a basic macro for linking user code into a relinkable library.

Note:
Non-native applications can connect to native queue managers, and vice versa. All combinations of native and non-native operation are valid and supported.

 

Building C++ sample programs

Note:
When linking C++ applications with the Native Static Library (MQMLIBN), you must link in the C++ runtime library (ZCPLSRL). This is illustrated in the sample link script (NMLDSAMP).

 

Native (using native static library MQMLIBN)

NMCPPALL
Usage: NMCPALL

Macro to compile all samples native using NMCCPP.

NMCCPP
Usage: NMCCPP source-code-file-name

This is a basic macro for compiling a C++ source file using the include files contained in subvolume ZMQSLIB. For example, to compile the sample IMQSGETP, use NMCCPP IMQSGETP. If the compilation is successful, the macro produces an object file with the last character of the file name replaced by the letter O; for example, IMQSGETO.

NMLDCPP
Usage: NMLDCPP exe-file-name

This basic macro links an object file with the static native MQI library MQMLIBN in ZMQSLIB.

NMLDCPPA
Usage: NMLDCPPA

This TACL macro binds each of the sample object files into executables using the NMLDSAMP macro.

NMBLDCPP
Usage: NMBUILDC

This TACL macro compiles and binds all the native C++ sample files using the macros NMCPPALL and NMLDCPPA.

 

Native (using SRL MQSRLLIB)

NMLDCPPS
Usage: NMLDCPPS MQSeries-Private-SRL-Volume

This basic macro links an object file with the native MQ SRL MQSRLLIB in ZMQSLIB.

NMLDCPSA
Usage: NMLDCPSA

This TACL macro binds each of the sample object files into executables using the NMLDCPPS macro.

NMBLDSCP
Usage: NMBLDSCP MQSeries Private SRL volume

This TACL macro compiles and binds all the native C sample files using the macros NMCPPALL and NMLDCPSA.

 

Building COBOL sample programs

 

Non-native (using non-native static libary MQMLIB)

The subvolume ZMQSSMPL contains the following files to be used for building sample COBOL applications.

COBSAMP
Usage: COBSAMP source-code-file-name

This is a basic macro for compiling a COBOL source file using the definition files contained in subvolume ZMQSLIB. For example, to compile the program AMQ0GBR0, use COBSAMP AMQ0GBR0. If the compilation is successful, the macro produces an object file with the last character of the file name replaced by the letter O; for example AMQ0GBRO.

BCOBSAMP
Usage: BCOBSAMP exe-file-name

This is a basic macro used to bind an object with the user libraries in ZMQSLIB. For example to bind the compiled sample AMQ0GBRO, use BCOBSAMP AMQ0GBR. The macro produces an executable called exe-file-name AMQ0GBR.

CCBSMPLS
Usage: CCBSMPLS

This TACL macro compiles each of the COBOL sample source code files.

BCBSMPLS
Usage: BIND /IN BCBSMPLS/

This bind input file binds each of the COBOL sample object files into executables.

BUILDCOB
Usage: BUILDCOB

This TACL macro compiles and binds all the COBOL sample files using the macros CCBSMPLS and BCBSMPLS.

 

Native (using native static library MQMLIBN)

NMCOBSMP
Usage: NMCOBSMP source-code-file-name

This is a macro for compiling native mode COBOL 'NMCOBOL' using the MQSeries native library MQMLIBN in ZMQSLIB. For example, to compile the program AMQ0GBR0, use NMCOBSMP AMQ0GBR0. If the compilation is successful, the macro produces an object file with the last character of the file name replaced by the letter O; for example AMQ0GBRO.

NMLDCOB
Usage: NMLDCOB exe-file-name

This macro binds an object with the MQSeries native library MQMLIBN in ZMQSLIB. For example to bind the compiled sample AMQ0GBRO, use NMLDCOB AMQ0GBR. The macro produces an executable called exe-file-name AMQ0GBR.

NMCOBALL
Usage: NMCOBALL

This TACL macro compiles each of the COBOL sample source code files using NMCOBSMP.

NMLDACOB
Usage: NMLDACOB

This bind input file binds each of the NMLDCOB sample object files into executables.

NMBLDCOB
Usage: NMBLDCOB

This TACL macro compiles and binds all the COBOL sample files using the macros NMCOBALL and NMLDACOB.

 

Native (using SRL MQSRLLIB)

NMCBSSMP
Usage: NMCBSSMP source-code-file-name

This is a macro for compiling native mode COBOL 'NMCOBOL' using the MQSeries SRL MQSRLLIB in ZMQSLIB. For example, to compile the program AMQ0GBR0, use NMCBSSMP AMQ0GBR0. If the compilation is successful, the macro produces an object file with the last character of the file name replaced by the letter O; for example AMQ0GBRO.

NMLDSCOB
Usage: NMLDSCOB exe-file-name

This macro binds an object with the MQSeries SRL MQSRLLIB in ZMQSLIB. For example to bind the compiled sample AMQ0GBRO, use NMLDSCOB AMQ0GBR. The macro produces an executable called exe-file-name AMQ0GBR.

NMCBSALL
Usage: NMCBSALL

This TACL macro compiles each of the COBOL sample source code files using NMCBSSMP.

NMLDSCOB
Usage: NMLDSCOB

This bind input file binds each of the NMLDSCOB sample object files into executables.

NMBLDSCB
Usage: NMBLDSCB

This TACL macro compiles and binds all the COBOL sample files using the macros NMCBSALL and NMLDSCOB.

 

Building TAL sample programs

 

Non-native (using non-native static library MQMLIB)

The subvolume ZMQSSMPL contains the following files to be used for building sample TAL programs.

TALSAMP
Usage: TALSAMP source-code-file-name

This is a basic macro for compiling a TAL source file using the definition files contained in subvolume Appendix I. MQSeries for Compaq NSK sample programs 335.ZMQSLIB. For example, to compile the program ZMQWRITT, use TALSAMP ZMQWRITT. If the compilation is successful, the macro produces an object file with the last character of the file name replaced by the letter O; for example ZMQWRITO.

BTALSAMP
Usage: BTALSAMP exe-file-name

This is a basic macro used to bind an object with the user libraries in ZMQSLIB. For example to bind the compiled sample ZMQWRITO, use BTALSAMP ZMQWRIT.

CTLSMPLS
Usage: CTLSMPLS

This TACL macro compiles each of the TAL sample source code files.

BTLSMPLS
Usage: BIND /IN BTLSMPLS/

This bind input file binds each of the TAL sample object files into executables.

BUILDTAL
Usage: BUILDTAL

This TACL macro compiles and binds all the TAL sample files using the macros CTLSMPLS and BTLSMPLS.

 

Building sample programs on OSS (native mode only)

The directory /opt/mqm/samp contains the sample programs for MQSeries and the make file MQMAKE.SMP. This MakeFile contains all the targets needed to build all the C, C++, and NMCOBOL samples

The directory /opt/mqm/inc contains all the copylibs and header files needed to build programs on OSS.

The readme.txt file contains information on building the OSS sample programs using the SRL MQSRLLIB or static library MQMLIBN.

Note:
The MQSeries SRL file and the native MQI library MQMLIBN exist only on the Guardian file system. You need to edit your build scripts and make files to point to them if needed, for example, /G/system/zmqslib/mqsrllib.

 

Running the sample programs

Before you can run any of the sample programs, a queue manager must be created and the default definitions set up. This is explained in WebSphere MQ System Administration Guide for WebSphere MQ for AIX, WebSphere MQ for Linux, WebSphere MQ for HP-UX, MQSeries for OS/2 Warp, WebSphere MQ for Solaris, and WebSphere MQ for Windows; for other platforms, see the appropriate System Management Guide.

 

On all platforms except OS/400

The samples need a set of queues to work with. Either use your own queues or run the sample MQSC file amqscos0.tst to create a set.

To do this on UNIX systems and Compaq OpenVMS Alpha, enter:

runmqsc QManagerName <amqscos0.tst >/tmp/sampobj.out

Check the sampobj.out file to ensure that there are no errors.

To do this on OS/2 and Windows systems enter:

runmqsc QManagerName  <amqscos0.tst > sampobj.out

Check the sampobj.out file to ensure that there are no errors. This file is in your current directory.

To do this on Compaq NonStop Kernel enter:

runmqsc -i $SYSTEM.ZMQSSMPL.AMQSCOMA

Check the sampobj.out file to ensure that there are no errors. This file will be found in your current directory.

The sample applications can now be run. Enter the name of the sample application followed by any parameters, for example:

amqsput myqueue qmanagername

where myqueue is the name of the queue on which the messages are going to be put, and qmanagername is the queue manager that owns myqueue.

See the description of the individual samples for information on the parameters that each of them expects.

 

On OS/400

You can use your own queues when you run the samples, or you can run the sample program AMQSAMP4 to create some sample queues. The source for this program is shipped in file QCLSRC in library QMQMSAMP. It can be compiled using the CRTCLPGM command.

To call one of the sample programs using data from member PUT in file AMQSDATA of library QMQMSAMP, use a command like: 

   CALL PGM(QMQM/AMQSPUT4) PARM('QMQMSAMP/AMQSDATA(PUT)')

The sample data only applies to the C/400(R) sample programs.

Note:
For a compiled module to use the IFS file system, specify the option SYSIFCOPT(*IFSIO) on CRTCMOD, then the file name, passed as a parameter, must be specified in the following format: 
home/me/myfile

 

Length of queue name

For the COBOL sample programs, when you pass queue names as parameters, you must provide 48 characters, padding with blank characters if necessary. Anything other than 48 characters causes the program to fail with reason code 2085.

 

Inquire, Set, and Echo examples

For the Inquire, Set, and Echo examples, the sample definitions cause the C versions of these samples to be triggered. If you want the COBOL versions change the process definitions:

SYSTEM.SAMPLE.INQPROCESS

SYSTEM.SAMPLE.SETPROCESS

SYSTEM.SAMPLE.ECHOPROCESS

On OS/2, Windows systems and UNIX do this by editing the amqscos0.tst file and changing the C executable file names to the COBOL executable file names before using the runmqsc command above.

On OS/400, you can use the CHGMQMPRC command (described in WebSphere MQ for iSeries V5.3 System Administration Guide), or edit and run AMQSAMP4 with the alternative definition.

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.

 

AIX is a trademark of the IBM Corporation in the United States, other countries, or both.