Program services and examples

JCICS supports the CICS program control commands, LINK, RETURN, and INVOKE APPLICATION.

For information about tools that allow Java programs to access existing CICS® application data, see Interacting with structured data from Java.

JCICS API mapping to EXEC CICS API lists the methods and JCICS classes that map to CICS program control commands.

LINK
You can transfer control to another program that is defined to CICS by using the link() method. The target program can be in any language that is supported by CICS.
RETURN
Only the pseudoconversational aspects of this command are supported. It is not necessary to make a CICS call to return; the application can terminate as normal. The pseudoconversational functions are supported by methods in the TerminalPrincipalFacility class: setNextTransaction() is equivalent to using the TRANSID option of RETURN; setNextCOMMAREA() is equivalent to using the COMMAREA option; while setNextChannel() is equivalent to using the CHANNEL option . These methods can be invoked at any time during the running of the program, and take effect when the program terminates.
INVOKE
Allows invocation of an application by naming an operation that corresponds to one of its program entry points, without having to know the name of the application entry point program and regardless of whether the program is public or private.

Samples

Example 1

The following code snippet shows how to use Task and Program to link to another CICS program. 

private static final String PROG_NAME = "EC01"; 1 
private static final int CA_LEN = 18 ;  2 
....
public static void main(String[] args) 3 
{
...
    Task task = Task.getTask(); 4 
    task.out.println("Hello world"); 5 
 
    Program prog = new Program(); 6 
    prog.setName(PROG_NAME);
    prog.setSyncOnReturn(false);  
    byte[] ca = new byte[CA_LEN]; 7 
    prog.link(ca);

Detailed explanation is as follows:

 1  2 
Initializes constants including the name of the CICS program and the length of the COMMAREA input.
 3 
The main(String[] args) constructor signifies this as the entry point for this CICS program, which allows this class to be named in the CICS-MainClass header in the OSGi bundle manifest.
 4 
Gets the Task object representing the CICS task that the current Java thread is using. This will drive the underlying CICS ASSIGN command on first usage.
 5 
Sends output to the print writer. The output will be directed to either the user’s terminal or the standard output (stdout) if there is no terminal.
 6 
Instantiates an instance of a Program, and then set properties such as the name and whether or not the LINK command uses the SYNCONRETURN option.
 7 
Creates a byte array and then passes this as input on the Program.link() method. This will drive an EXEC CICS LINK command to the CICS program named in the prog.setName method. The COMMAREA will be passed as a byte array, which is an unstructured array of bytes of the specified length. Most CICS programs expect structured data as input. Therefore, if you need to build a Java bean to map to this, you can use IBM® Record Generator for Java or Rational® J2C Tools to build wrapper classes to map the records.

Note that there is no return type from the Program.link() method; instead the data is updated in the original place within the referenced COMMAREA.

Example 2

The program that is invoked by a LINK command can also be written in Java, and in this case it passes the COMMAREA as a simple byte array. The following sample Java version of the EC01 CICS COBOL program shows how to use the CommAreaHolder class to receive the byte array mapping to the COMMAREA.

public class LinkServEC01 
{
    //Initialize constants
    private static final int CA_LEN = 18 ;  
    private static final String CA_LEN_ABCODE = "LEN";
    private static final SimpleDateFormat dfTime = new SimpleDateFormat("dd/MM/yy HH:mm:ss"); 
    //Get the local encoding of the CICS region, this defaults to EBCDIC  
    private static final String CCSID = System.getProperty("com.ibm.cics.jvmserver.local.ccsid");
 
    public static void main(CommAreaHolder cah)  
    {
 
        Task task = Task.getTask();
 
        //Check input array is long enough, and terminate the task using an abend if input is too short
        if (cah.getValue().length < CA_LEN )
        {
            task.abend(CA_LEN_ABCODE);          
        }
 
        //Build time string for return to caller
        Date timestamp = new Date();            
        byte ba[] = dfTime.format(timestamp).getBytes(CCSID);
        //Create byte array from the time string using the CICS encoding and copy into the CommAreaHolder for return to the calling program as the COMMAREA
        System.arraycopy (ba, 0, cah.getValue(), 0, ba.length);
    }
....
Learn more

For more samples on how to perform CICS LINK operations using both COMMAREAs, channels, and containers, see the com.ibm.cicsdev.link sample at GitHub.