Using CICS DPL programs with the bridge

To link to another program that has been defined to CICS, a CICS application can issue a command like this:

EXEC CICS LINK PROGRAM(name) COMMAREA(data-area)

For the complete syntax of this command, see the CICS Application Programming Reference book.

If you want a WebSphere MQ application to run a CICS application that invokes a CICS DPL program, the WebSphere MQ application must send a structured message to the bridge request queue. In the simplest case, the message data consists only of the name of a DPL program to be run. Follow this by COMMAREA data if you want to make data available to the DPL program when it starts.

If you want to run more than one DPL program within a unit of work, or you prefer a specific transaction code (overwriting the default CKBP), or you require certain levels of authorization to run the DPL program, you must supply information in an MQCIH. The MQCIH must precede the program name and any COMMAREA data that you send.

CICS DPL bridge message structure

These examples show the different structures you can use for messages that run DPL programs through the bridge.

Use this structure for an application that runs a single DPL program using default processing options, and does not send or receive COMMAREA data:
```
*------*----------*
| MQMD | ProgName |
*------*----------*
```
The program specified by ProgName is invoked by CICS as a DPL program.
Use this structure for an application that runs a single DPL program using default processing options, and sends and receives COMMAREA data:
```
*------*----------*--------------*
| MQMD | ProgName | CommareaData |
*------*----------*--------------*
```
Use this structure for an application that runs one or more DPL programs within a unit of work, or needs specific authorization to run the program, but does not send or receive COMMAREA data:
```
*------*-------*----------*
| MQMD | MQCIH | ProgName |
*------*-------*----------*
```
Use this structure for an application that invokes one or more DPL programs within a unit of work, or needs specific authorization to run the program, and sends and receives COMMAREA data:
```
*------*-------*----------*--------------*
| MQMD | MQCIH | ProgName | CommareaData |
*------*-------*----------*--------------*
```

If a bridge task running a DPL program ends abnormally, a message is returned to the reply queue with the following structure, whether or not the inbound message preceding the failure contained an MQCIH:

*------*-------*---------------*
| MQMD | MQCIH | CSQC* message |
*------*-------*---------------*

CSQC* message represents an error message that indicates the error type. The value of field MQCIH.Format is set to MQFMT_STRING, so that the message can be properly converted if the final destination uses a different CCSID and encoding. The MQCIH also contains other fields that you can use to diagnose the problem.

Notes:

The MQMD is shown in the examples to help you visualize the overall structure of the message. This is the structure that you see if you use the general queue browser utility of WebSphere MQ SupportPac^(TM) MA10 "MQSeries for MVS/ESA - ISPF utilities".
When you want to send only a program name, and no COMMAREA data, to the bridge, the program name must be 8 characters long. It must not be a name that is padded to the right with spaces, or the bridge will report a COMMAREA negative length error.
When you want to send COMMAREA data, you must pad the program name with spaces to the right, to give a total length of eight characters.
You can include control data in the message to specify unit of work management, and to provide data for security checking, when you include a WebSphere MQ CICS information header (CIH) in the message.

Application programming for the CICS DPL bridge

This C-language code fragment shows how you can construct a message buffer when you want to invoke a DPL program with COMMAREA data, and include a WebSphere MQ CICS Information Header (MQCIH).

/* 
#defines                                                     */
#define   PGMNAME "DPLPGM"              /* DPL program name  */
#define   PGMNAMELEN 8
#define   CALEN 100                     /* Commarea length   */

  ·
  ·
  ·

/* Data declarations                                         */
MQMD   mqmd ;                   /* Message descriptor        */
MQCIH  mqcih ;                  /* CICS information header   */
MQCHAR  * Commarea ;            /* Commarea pointer          */
MQCHAR  * MsgBuffer ;           /* Message buffer pointer    */

  ·
  ·
  ·

/* allocate storage for the buffers                          */
 
Commarea  = malloc(CALEN * sizeof(MQCHAR)) ;
MsgBuffer = malloc(sizeof(MQCIH) + PGMNAMELEN + CALEN) ;

  ·
  ·
  ·

/* Initialize commarea with data                             */

  ·
  ·
  ·

/* Initialize fields in the MQMD as required, including:     */
 
mqmd.MsgId = MQMI_NONE ;
mqmd.CorrelId = MQCI_NEW_SESSION ;
 
/* Initialize fields in the MQCIH as required                */

  ·
  ·
  ·

/* Copy the MQCIH to the start of the message buffer         */
 
memcpy(MsgBuffer, &mqcih, sizeof(MQCIH)) ;
 
/* Set 8 bytes after the MQCIH to spaces                     */ 
 
memset(MsgBuffer + sizeof(MQCIH), ' ', PGMNAMELEN) ;
 
/* Append the program name to the MQCIH.  If it is less than */
/* 8 characters, it is now padded to the right with spaces.  */
 
strncpy(MsgBuffer + sizeof(MQCIH), PGMNAME, PGMNAMELEN) ;
 
/* Append the commarea after the program name                */
 
memcpy(MsgBuffer + sizeof(MQCIH) + PGMNAMELEN, &Commarea
   CALEN ) ;
 
/* The message buffer is now ready for the MQPUT             */
/* to the Bridge Request Queue.                              */

  ·
  ·
  ·

The DPL program that is invoked must be defined to CICS with EXECUTIONSET=DPLSUBSET, and it must conform to the DPL subset rules. See the CICS Application Programming Guide for further details.

Managing units of work for the CICS DPL bridge

If your Bridge application is running just a single DPL program, set the value of MQCIH.UOWControl to MQCUOWC_ONLY. However, if your application is sending and receiving multiple messages, you must handle units of work correctly for the CICS DPL bridge. If you want to run multiple user programs within a unit of work, you should

set the value of MQCIH.UOWControl to MQCUOWC_FIRST in the first request
set MQCUOWC_MIDDLE in any intermediate requests
set MQCUOWC_LAST in the last request

Your application can send multiple request messages within a unit of work before receiving any response messages. At any time after the first message, you can terminate the unit of work by sending a message with MQCIH.UOWControl set to MQCUOWC_COMMIT or MQCUOWC_BACKOUT.