Building an application on z/OS

You can write C++ programs for three of the environments that WebSphere MQ for z/OS supports:

• Batch
• RRS batch
• CICS

When you have written the C++ program for your WebSphere MQ application, you have to create an executable application by compiling, pre-linking, and link-editing it.

WebSphere MQ C++ for z/OS is implemented as z/OS DLLs for the IBM C++ for z/OS language. Using DLLs, you have to concatenate the supplied definition side-decks with the compiler output at pre-link time. This allows the linker to check your calls to the WebSphere MQ C++ member functions.

Note:

There are three sets of side-decks for each of the three environments.

To build a WebSphere MQ for z/OS C++ application, you need to create and run JCL. Use the following procedure:

1. If your application runs under CICS, use the CICS-supplied procedure to translate CICS commands in your program.

   In addition, for CICS applications you need to:

   1. Add, the SCSQLOAD library to the DFHRPL concatenation.
   2. Define the CSQCAT1 CEDA group using the member IMQ4B100 in the SCSQPROC library.
   3. Install CSQCAT1.
2. Compile the program to produce object code. The JCL for your compilation must include statements that make the product data definition files available to the compiler. The data definitions are supplied in the following WebSphere MQ for z/OS libraries:
   • thlqual.SCSQC370
   • thlqual.SCSQHPPS

   Be sure to specify the /cxx compiler option.

   Note:

   The name thlqual is the high level qualifier of the WebSphere MQ installation library on z/OS.

3. Prelink the object code created in step 2, including the following definition side-decks, which are supplied in thlqual.SCSQDEFS:
   • imqs23dm and imqb23dm for batch
   • imqs23dr and imqb23dr for RRS batch
   • imqs23dc and imqb23dc for CICS
4. Link-edit the object code created in step 3, to produce a load module, and store it in your application load library.

To run batch or RRS batch programs, the libraries thlqual.SCSQAUTH and thlqual.SCSQLOAD must be included in the STEPLIB, or JOBLIB data set concatenation.

To run a CICS program, you must first get your system administrator to define it to CICS as a WebSphere MQ program and transaction. You can then run it in the usual way.

Running sample programs on z/OS

WebSphere MQ for z/OS supplies three sample programs, together with JCL to run them. The programs are described in Sample programs.

The sample applications are supplied in source form only. The files are:

Table 4. z/OS sample program files

To run the samples, you need to compile and link-edit them as with any C++ program (see Building an application on z/OS). Use the supplied JCL to construct and run a batch job. You must initially customize the JCL, by following the commentary included with it.

Building and running applications under z/OS UNIX System Services

In order to build an application under the UNIX System Services shell, you must give the compiler access to the WebSphere MQ include files (located in thlqual.SCSQC370 and thlqual.SCSQHPPS), and link against two of the DLL side-decks (located in thlqual.SCSQDEFS). At runtime, the application needs access to the WebSphere MQ datasets thlqual.SCSQLOAD, thlqual.SCSQAUTH, and one of the language specific datasets, such as thlqual.SCSQANLE.

Sample commands to compile the HELLO WORLD C++ sample program

1. Copy the sample into the HFS using the TSO oput command, or use FTP. The rest of this example assumes that you copied the sample into a directory called /u/fred/sample, and named it imqwrld.cpp.
2. Log into the UNIX System Services shell, and change to the directory where you placed the sample.
3. Set up the C++ compiler so that it can accept the DLL side-deck and .cpp files as input:

   /u/fred/sample:> export _CXX_EXTRA_ARGS=1
   /u/fred/sample:> export _CXX_CXXSUFFIX="cpp"
   

4. Compile and link the sample program. The following command links the program with the batch side-decks; the RRS batch side-decks can be used instead. The \ character is used to split the command over more than one line. Do not enter this character, enter the command as a single line:

   /u/fred/sample:> c++ -o imqwrld -I "//'thlqual.SCSQC370'" \
   -I "//'thlqual.SCSQHPPS'" imqwrld.cpp \
   "//'thlqual.SCSQDEFS(IMQS23DM)'" "//'thlqual.SCSQDEFS(IMQB23DM)'"
   

For more information on the TSO oput command, refer to the z/OS UNIX System Services Command Reference.

It is also possible to use the make utility to simplify building C++ programs. Here is a sample makefile to build the HELLO WORLD C++ sample program. It separates the compile and link stages. The environment should be set up as in step 3 above before running make.

flags = -I "//'thlqual.SCSQC370'" -I "//'thlqual.SCSQHPPS'"
decks = "//'thlqual.SCSQDEFS(IMQS23DM)'" "//'thlqual.SCSQDEFS(IMQB23DM)'"
 
imqwrld: imqwrld.o
   c++ -o imqwrld imqwrld.o $(decks)
 
imqwrld.o: imqwrld.cpp
   c++ -c -o imqwrld $(flags) imqwrld.cpp

Refer to the z/OS UNIX System Services Programming Tools manual for more information on using make.

Sample commands to run the HELLO WORLD C++ sample program

1. Log into the UNIX System Services shell, and change to the directory where you built the sample.
2. Set up the STEPLIB environment variable to include the WebSphere MQ datasets:

   /u/fred/sample:> export STEPLIB=$STEPLIB:thlqual.SCSQLOAD
   /u/fred/sample:> export STEPLIB=$STEPLIB:thlqual.SCSQAUTH
   /u/fred/sample:> export STEPLIB=$STEPLIB:thlqual.SCSQANLE
   

3. Run the sample:

   /u/fred/sample:> ./imqwrld