Migrating from COMMAREAs to channels

This topic describes:

Migration of existing functions

Migration to the new function

This section describes how you can migrate several types of existing application to use channels and containers rather than communication areas (COMMAREAs).

It's possible to replace a COMMAREA by a channel with a single container. While this may seem the simplest way to move from COMMAREAs to channels and containers, it's not good practice to do this. Because you're taking the time to change your application programs to exploit this new function, you should implement the "best practices" for channels and containers. Channels have several advantages over COMMAREAs and it pays to design your channels to make the most of these improvements.

Migrating LINK commands that pass COMMAREAs

To migrate two programs which use a COMMAREA on a LINK command to exchange a structure, change the instructions shown in Table 28.

Table 28. Migrating LINK commands that pass COMMAREAs
Program Before After
PROG1
EXEC CICS LINK 
     PROGRAM(PROG2) 
     COMMAREA(structure)
EXEC CICS PUT CONTAINER(structure-name) 
          CHANNEL(channel-name) 
          FROM(structure)
EXEC CICS LINK PROGRAM(PROG2) 
          CHANNEL(channel-name)

...
EXEC CICS GET CONTAINER(structure-name) 
          CHANNEL(channel-name) 
          INTO(structure)
PROG2
EXEC CICS ADDRESS 
  COMMAREA(structure-ptr)
...
RETURN
EXEC CICS GET CONTAINER(structure-name) 
          INTO(structure)
...
EXEC CICS PUT CONTAINER(structure-name) 
          FROM(structure)
RETURN

Migrating XCTL commands that pass COMMAREAs

To migrate two programs which use a COMMAREA on an XCTL command to pass a structure, change the instructions shown in Table 29.

Table 29. Migrating XCTL commands that pass COMMAREAs
Program Before After
PROG1
EXEC CICS XCTL 
     PROGRAM(PROG2) 
     COMMAREA(structure)
EXEC CICS PUT CONTAINER(structure-name) 
          CHANNEL(channel-name) 
          FROM(structure)
EXEC CICS XCTL PROGRAM(PROG2) 
          CHANNEL(channel-name)
...
PROG2
EXEC CICS ADDRESS 
  COMMAREA(structure-ptr)
...
EXEC CICS GET CONTAINER(structure-name) 
          INTO(structure)
...

Migrating pseudoconversational COMMAREAs on RETURN commands

To migrate two programs which use COMMAREAs to exchange a structure as part of a pseudoconversation, change the instructions shown in Table 30.

Table 30. Migrating pseudoconversational COMMAREAs on RETURN commands
Program Before After
PROG1
EXEC CICS RETURN
     TRANSID(PROG2) 
     COMMAREA(structure) 
EXEC CICS PUT CONTAINER(structure-name)
          CHANNEL(channel-name) 
          FROM(structure)  
EXEC CICS RETURN TRANSID(TRAN2)     
          CHANNEL(channel-name)
PROG2
EXEC CICS ADDRESS
  COMMAREA(structure-ptr)
EXEC CICS GET CONTAINER(structure-name) 
           INTO(structure) 

Migrating START data

To migrate two programs which use START data to exchange a structure, change the instructions shown in Table 31.

Table 31. Migrating START data
Program Before After
PROG1
EXEC CICS START 
     TRANSID(TRAN2) 
     FROM(structure)
EXEC CICS PUT CONTAINER(structure-name)         
          CHANNEL(channel-name) 
          FROM(structure) 
EXEC CICS START TRANSID(TRAN2)        
          CHANNEL(channel-name)
PROG2
EXEC CICS RETRIEVE 
     INTO(structure)
EXEC CICS GET CONTAINER(structure-name)
            INTO(structure) 

Note that the new version of PROG2 is the same as that in the pseudoconversational example.

Migrating dynamically-routed applications

EXEC CICS LINK and EXEC CICS START commands, which can pass either COMMAREAs or channels, can be dynamically routed.

When a LINK or START command passes a COMMAREA rather than a channel, the routing program can, depending on the type of request, inspect or change the COMMAREA's contents. For LINK requests and transactions started by terminal-related START requests (which are handled by the dynamic routing program) but not for non-terminal-related START requests (which are handled by the distributed routing program) the routing program is given, in the DYRACMAA field of its communication area, the address of the application's COMMAREA, and can inspect and change its contents.

Note:
The routing program's communication area is mapped by the DFHDYPDS DSECT.

If you migrate a dynamically-routed EXEC CICS LINK or START command to use a channel rather than a COMMAREA, the routing program is passed, in the DYRCHANL field of DFHDYPDS, the name of the channel. Note that the routing program is given the name of the channel, not its address, and so is unable to use the DYRCHANL field to inspect or change the contents of the channel's containers.

To give the routing program the same kind of functionality with channels, an application that uses a channel can create, within the channel, a special container named DFHROUTE. If the application issues a LINK or terminal-related START request (but not a non-terminal-related START request) that is to be dynamically routed, the dynamic routing program is given, in the DYRACMAA field of DFHDYPDS, the address of the DFHROUTE container, and can inspect and change its contents.

If you are migrating a program to pass a channel rather than a COMMAREA, you could use its existing COMMAREA structure to map DFHROUTE.

For introductory information about dynamic and distributed routing, see the CICS Intercommunication Guide. For information about writing a dynamic or distributed routing program, see the CICS Customization Guide.

[[ Contents Previous Page | Next Page Index ]]