Program control

This section describes how to access and use a program other than the one that is currently executing.

Program control uses IccProgram class, one of the resource classes.

Programs may be loaded, unloaded and linked to, using an IccProgram object. An IccProgram object can be interrogated to obtain information about the program. See IccProgram class for more details.

The example shown here shows one program calling another two programs in turn, with data passing between them via a COMMAREA. One program is assumed to be local, the second is on a remote CICS® system. The programs are in two files, ICC$PRG1 and ICC$PRG2. See C++ sample programs for the location of these files and the expected output from these sample programs.

Most of the terminal IO in these samples has been omitted from the code that follows.

#include "icceh.hpp"
#include "iccmain.hpp"
void IccUserControl::run()
{

The code for both programs starts by including the header files for the Foundation Classes and the stub for main method. The user code is located in the run method of the IccUserControl class for each program.

IccSysId sysId( "ICC2" );
IccProgram icc$prg2( "ICC$PRG2" );
IccProgram remoteProg( "ICC$PRG3" );
IccBuf commArea( 100, IccBuf::fixed );

The first program (ICC$PRG1) creates an IccSysId object representing the remote region, and two IccProgram objects representing the local and remote programs that will be called from this program. A 100 byte, fixed length buffer object is also created to be used as a communication area between programs.

icc$prg2.load();
if (icc$prg2.condition() == IccCondition::NORMAL)
{
term->sendLine( "Loaded program: %s <%s> Length=%ld Address=%x",
icc$prg2.name(),
icc$prg2.conditionText(),
icc$prg2.length(),
icc$prg2.address() );
icc$prg2.unload();
}

The program then attempts to load and interrogate the properties of program ICC$PRG2.

 commArea = "DATA SET BY ICC$PRG1";
icc$prg2.link( &commArea );

The communication area buffer is set to contain some data to be passed to the first program that ICC$PRG1 links to (ICC$PRG2). ICC$PRG1 is suspended while ICC$PRG2 is run.

The called program, ICC$PRG2, is a simple program, the gist of which is as follows:

IccBuf& commArea = IccControl::commArea();
commArea = "DATA RETURNED BY ICC$PRG2";
return;

ICC$PRG2 gains access to the communication area that was passed to it. It then modifies the data in this communication area and passes control back to the program that called it.

The first program (ICC$PRG1) now calls another program, this time on another system, as follows:

remoteProg.setRouteOption( sysId );
commArea = "DATA SET BY ICC$PRG1";
remoteProg.link( &commArea );

The setRouteOption requests that calls on this object are routed to the remote system. The communication area is set again (because it will have been changed by ICC$PRG2) and it then links to the remote program (ICC$PRG3 on system ICC2).

The called program uses CICS temporary storage but the three lines we consider are:

IccBuf& commArea = IccControl::commArea();
commArea = "DATA RETURNED BY ICC$PRG3";
return;

Again, the remote program (ICC$PRG3) gains access to the communication area that was passed to it. It modifies the data in this communication area and passes control back to the program that called it.

 return;
};

Finally, the calling program itself ends and returns control to CICS.