Preparing your program to run

After you have written the program for your WebSphere MQ application, to create an executable application you have to compile or assemble it, then link-edit the resulting object code with the stub program that WebSphere MQ for z/OS supplies for each environment it supports. How you prepare your program depends on both the environment (batch, CICS, or IMS(BMP or MPP)) in which the application will run, and the structure of the data sets on your z/OS installation. The details are described in the following sections.

Dynamically calling the WebSphere MQ stub describes an alternative method of making MQI calls in your programs so that you do not need to link-edit a WebSphere MQ stub. This method is not available for all languages and environments.

Do not link-edit a higher level of stub program than that of the version of WebSphere MQ for z/OS on which your program is running. For example, a program running on MQSeries for OS/390, V5.2 must not be link-edited with a stub program supplied with WebSphere MQ for z/OS, V5.3.

Building z/OS batch applications

To build an application for WebSphere MQ for z/OS that runs under z/OS batch, create job control language (JCL) that performs these tasks:

Compile (or assemble) the program to produce object code. The JCL for your compilation must include SYSLIB 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:

For COBOL, thlqual.SCSQCOBC
For assembler language, thlqual.SCSQMACS
For C, thlqual.SCSQC370
For PL/I, thlqual.SCSQPLIC
For a C application, prelink the object code created in step 1.
Link-edit the object code created in step 1 (or step 2 for a C application) to produce a load module. When you link-edit the code, you must include one of the WebSphere MQ for z/OS batch stub programs (CSQBSTUB or one of the RRS stub programs: CSQBRRSI or CSQBRSTB).

CSQBSTUB
single-phase commit provided by WebSphere MQ for z/OS
CSQBRRSI
two-phase commit provided by RRS via the MQI
CSQBRSTB
two-phase commit provided by RRS directly

Note:
If you use CSQBRSTB then you must also link-edit your application with ATRSCSS from SYS1.CSSLIB. Figure 19 and Figure 20 show fragments of JCL to do this. The stubs are language-independent and are supplied in library thlqual.SCSQLOAD.
Store the load module in an application load library.

Figure 19. Fragments of JCL to link-edit the object module in the batch environment, using single-phase commit


  ·
  ·
  ·

//*
//* WEBSPHERE MQ FOR Z/OS LIBRARY CONTAINING BATCH STUB
//*
//CSQSTUB   DD  DSN=++HLQ.MQM100++.SCSQLOAD,DISP=SHR
//*

  ·
  ·
  ·

//SYSIN     DD *
  INCLUDE CSQSTUB(CSQBSTUB)

  ·
  ·
  ·

/*

Figure 20. Fragments of JCL to link-edit the object module in the batch environment, using two-phase commit


  ·
  ·
  ·

//*
//* WEBSPHERE MQ FOR Z/OS LIBRARY CONTAINING BATCH STUB
//*
//CSQSTUB   DD  DSN=++HLQ.MQM100++.SCSQLOAD,DISP=SHR
//CSSLIB    DD  DSN=SYS1.CSSLIB,DISP=SHR
//*

  ·
  ·
  ·

//SYSIN     DD *
  INCLUDE CSQSTUB(CSQBRSTB)
  INCLUDE CSSLIB(ATRSCSS)

  ·
  ·
  ·

/*

To run a batch or RRS program, you must include the libraries thlqual.SCSQAUTH and thlqual.SCSQLOAD in the STEPLIB or JOBLIB data set concatenation.

To run a TSO program, you must include the libraries thlqual.SCSQAUTH and thlqual.SCSQLOAD in the STEPLIB used by the TSO session.

To run an OpenEdition^(R) batch program from the OpenEdition shell, add the libraries thlqual.SCSQAUTH and thlqual.SCSQLOAD to the STEPLIB specification in your $HOME/.profile like this:

  STEPLIB=thlqual.SCSQAUTH:thlqual.SCSQLOAD
  export STEPLIB

Building CICS applications

To build an application for WebSphere MQ for z/OS that runs under CICS, you must:

Translate the CICS commands in your program into the language in which the rest of your program is written
Compile or assemble the output from the translator to produce object code
Link-edit the object code to create a load module

CICS provides a procedure to execute these steps in sequence for each of the programming languages it supports.

For CICS Transaction Server for z/OS, the CICS Transaction Server for z/OS System Definition Guide describes how to use these procedures and the CICS/ESA(R) Application Programming Guide gives more information on the translation process.

You must include:

In the SYSLIB statement of the compilation (or assembly) stage, 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:

For COBOL, thlqual.SCSQCOBC
For assembler language, thlqual.SCSQMACS
For C, thlqual.SCSQC370
For PL/I, thlqual.SCSQPLIC
In your link-edit JCL, the WebSphere MQ for z/OS CICS stub program (CSQCSTUB). Figure 21 shows fragments of JCL code to do this. The stub is language-independent and is supplied in library thlqual.SCSQLOAD.

When you have completed these steps, store the load module in an application load library and define the program to CICS in the usual way.

Figure 21. Fragments of JCL to link-edit the object module in the CICS environment


  ·
  ·
  ·

//*
//* WEBSPHERE MQ FOR Z/OS LIBRARY CONTAINING CICS STUB
//*
//CSQSTUB   DD  DSN=++HLQ.MQM100++.SCSQLOAD,DISP=SHR
//*

  ·
  ·
  ·

//LKED.SYSIN DD *
  INCLUDE CSQSTUB(CSQCSTUB)

  ·
  ·
  ·

/*

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

Building IMS (BMP or MPP) applications

If you are building batch DL/I programs, see Building z/OS batch applications. To build other applications that run under IMS (either as a BMP or an MPP), create JCL that performs these tasks:

Compile (or assemble) the program to produce object code. The JCL for your compilation must include SYSLIB 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:

For COBOL, thlqual.SCSQCOBC
For assembler language, thlqual.SCSQMACS
For C, thlqual.SCSQC370
For PL/I, thlqual.SCSQPLIC
For a C application, prelink the object module created in step 1.
Link-edit the object code created in step 1 (or step 2 for a C/370 application) to produce a load module:
1. Include the IMS language interface module (DFSLI000).
2. Include the WebSphere MQ for z/OS IMS stub program (CSQQSTUB). Figure 22 shows fragments of JCL to do this. The stub is language independent and is supplied in library thlqual.SCSQLOAD.
  Note:
  If you are using COBOL, you should select the NODYNAM compiler option to enable the linkage editor to resolve references to CSQQSTUB unless you intend to use dynamic linking as described in Dynamically calling the WebSphere MQ stub.
Store the load module in an application load library.

Figure 22. Fragments of JCL to link-edit the object module in the IMS environment


  ·
  ·
  ·

//*
//* WEBSPHERE MQ FOR Z/OS LIBRARY CONTAINING IMS STUB
//*
//CSQSTUB   DD  DSN=++HLQ.MQM100++.SCSQLOAD,DISP=SHR
//*

  ·
  ·
  ·

//LKED.SYSIN DD *
  INCLUDE CSQSTUB(CSQQSTUB)

  ·
  ·
  ·

/*

Before you run an IMS program, your system administrator must define it to IMS as a WebSphere MQ program and transaction: you can then run it in the usual way.