com.ibm.cics.server
Class Program

java.lang.Object
  extended bycom.ibm.cics.server.API
      extended bycom.ibm.cics.server.Resource
          extended bycom.ibm.cics.server.RemotableResource
              extended bycom.ibm.cics.server.Program
All Implemented Interfaces:
java.io.Serializable

public class Program
extends RemotableResource
implements java.io.Serializable

This Bean provides the Java interface to CICS Program Control equivalent to the LINK and XCTL commands.

In addition to the properties it inherits from RemotableResource, it defines the following properties:

syncOnReturn
A boolean which defines whether or not a remote program will commit its work as soon as it returns.
transId
A String which defines the name of the mirror transaction that should be used to run the mirror program on the remote system.

Version:
1.3
Author:
John Colgrave
See Also:
Serialized Form

Constructor Summary
Program()
          Construct a Program bean.
 
Method Summary
 boolean getSyncOnReturn()
          Will this program always performs a SYNCPOINT when it returns? This only applies to remote programs.
 java.lang.String getTransId()
          Return the name of the CICS (mirror) transaction to be used to run the remote program.
 void link()
          Perform a simple link to the program without passing in a COMMAREA.
 void link(byte[] CA)
          Link to the program, passing in a COMMAREA.
 void link(byte[] CA, int DATALENGTH)
          Version of the link() method that takes the DATALENGTH parameter.
 void link(Channel chan)
          Perform a link to the program passing a CHANNEL.
 void link(com.ibm.record.IByteBuffer ibb)
          Version of the link() method that takes a single IByteBuffer.
 void link(com.ibm.record.IByteBuffer im, com.ibm.record.IByteBuffer om)
          Version of the link() method that takes a separate IByteBuffer for the input data and output data.
 void setSyncOnReturn(boolean syncOnReturn)
          Control whether the program always performs a SYNCPOINT when it returns.
 void setTransId(java.lang.String TRANSID)
          Set the transaction name to be used when running the program remotely, instead of CPMI.
 void xctl()
          Transfer control to the program, terminating the current program.
 void xctl(byte[] CA)
          Transfer control to the program, terminating the current program, passing in a COMMAREA.
 void xctl(Channel chan)
          Transfer control to the program, terminating the current program, passing a CHANNEL.
 
Methods inherited from class com.ibm.cics.server.RemotableResource
getSysId, setSysId
 
Methods inherited from class com.ibm.cics.server.Resource
getDescription, getName, setDescription, setName
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Program

public Program()
Construct a Program bean.

Method Detail

getSyncOnReturn

public boolean getSyncOnReturn()
Will this program always performs a SYNCPOINT when it returns? This only applies to remote programs.

Returns:
boolean an indication if SYNCONRETURN will always apply

getTransId

public java.lang.String getTransId()
Return the name of the CICS (mirror) transaction to be used to run the remote program.

Returns:
String the name of the (mirror) transaction to be used

link

public void link()
          throws InvalidRequestException,
                 LengthErrorException,
                 NotAuthorisedException,
                 InvalidProgramIdException,
                 RolledBackException,
                 InvalidSystemIdException,
                 TerminalException
Perform a simple link to the program without passing in a COMMAREA.

Throws:
InvalidRequestException - This exception can only occur when the program being linked to is remote. It occurs for one of the following reasons:
  • setSyncOnReturn(true) has been called on the program but the program calling the link method is already in conversation with a mirror task (that is, a logical unit-of-work is in progress) in the remote region. In this case, the linked-to program is in an incorrect state to support the SYNCONRETURN option.
  • The program calling the link method is already in conversation with a mirror task and the transaction name specified (via a call to setTransId()) is different from the transaction name of the active mirror.
LengthErrorException - LENGERR occurred.
NotAuthorisedException - NOTAUTH occurred.
InvalidProgramIdException - PGMIDERR occurred.
RolledBackException - ROLLEDBACK occurred.
InvalidSystemIdException - SYSIDERR occurred.
TerminalException - TERMERR occurred.

link

public void link(byte[] CA)
          throws InvalidRequestException,
                 LengthErrorException,
                 NotAuthorisedException,
                 InvalidProgramIdException,
                 RolledBackException,
                 InvalidSystemIdException,
                 TerminalException
Link to the program, passing in a COMMAREA.

Parameters:
CA - A byte[] that is the COMMAREA to be passed to the program.
Throws:
InvalidRequestException - INVREQ occurred.
LengthErrorException - LENGERR occurred.
NotAuthorisedException - NOTAUTH occurred.
InvalidProgramIdException - PGMIDERR occurred.
RolledBackException - ROLLEDBACK occurred.
InvalidSystemIdException - SYSIDERR occurred.
TerminalException - TERMERR occurred.

link

public void link(byte[] CA,
                 int DATALENGTH)
          throws InvalidRequestException,
                 LengthErrorException,
                 NotAuthorisedException,
                 InvalidProgramIdException,
                 RolledBackException,
                 InvalidSystemIdException,
                 TerminalException
Version of the link() method that takes the DATALENGTH parameter. This method is the only way that DATALENGTH can be specified.

Parameters:
CA - A byte[] that is the COMMAREA to be passed to the program.
DATALENGTH - The amount of data to send from the COMMAREA. This parameter can be used to avoid transmitting unnecessary data over the network if the amount of data to be sent to the remote program is less than the amount of data expected back.
Throws:
InvalidRequestException - INVREQ occurred.
LengthErrorException - LENGERR occurred.
NotAuthorisedException - NOTAUTH occurred.
InvalidProgramIdException - PGMIDERR occurred.
RolledBackException - ROLLEDBACK occurred.
InvalidSystemIdException - SYSIDERR occurred.
TerminalException - TERMERR occurred.

link

public void link(com.ibm.record.IByteBuffer ibb)
          throws InvalidRequestException,
                 LengthErrorException,
                 NotAuthorisedException,
                 InvalidProgramIdException,
                 RolledBackException,
                 InvalidSystemIdException,
                 TerminalException
Version of the link() method that takes a single IByteBuffer. This method supports uses of link where the same structure is used for both the request data and the response data.

Parameters:
ibb - A reference to an object which implements the IByteBuffer. The same mapping is used for both the initial data passed to the program and the data returned by the program.
Throws:
InvalidRequestException - INVREQ occurred.
LengthErrorException - LENGERR occurred.
NotAuthorisedException - NOTAUTH occurred.
InvalidProgramIdException - PGMIDERR occurred.
RolledBackException - ROLLEDBACK occurred.
InvalidSystemIdException - SYSIDERR occurred.
TerminalException - TERMERR occurred.

link

public void link(com.ibm.record.IByteBuffer im,
                 com.ibm.record.IByteBuffer om)
          throws InvalidRequestException,
                 LengthErrorException,
                 NotAuthorisedException,
                 InvalidProgramIdException,
                 RolledBackException,
                 InvalidSystemIdException,
                 TerminalException
Version of the link() method that takes a separate IByteBuffer for the input data and output data. If the input data is shorter than the output data then this method will set the DATALENGTH option in the underlying CICS API.

Parameters:
im - A reference to an object which implements the IByteBuffer. This object maps the input data. If no mapping of the input data is required then a special identity map must be supplied.
om - A reference to an object which implements the IByteBuffer. This object maps the output data. If no mapping of the output data is required then a special identity map must be supplied.
Throws:
InvalidRequestException - INVREQ occurred.
LengthErrorException - LENGERR occurred.
NotAuthorisedException - NOTAUTH occurred.
InvalidProgramIdException - PGMIDERR occurred.
RolledBackException - ROLLEDBACK occurred.
InvalidSystemIdException - SYSIDERR occurred.
TerminalException - TERMERR occurred.

link

public void link(Channel chan)
          throws InvalidRequestException,
                 LengthErrorException,
                 NotAuthorisedException,
                 InvalidProgramIdException,
                 RolledBackException,
                 InvalidSystemIdException,
                 TerminalException,
                 ChannelErrorException
Perform a link to the program passing a CHANNEL.

Parameters:
chan - A reference to the Channel
Throws:
InvalidRequestException
LengthErrorException - LENGERR occurred.
NotAuthorisedException - NOTAUTH occurred.
InvalidProgramIdException - PGMIDERR occurred.
RolledBackException - ROLLEDBACK occurred.
InvalidSystemIdException - SYSIDERR occurred.
TerminalException - TERMERR occurred.
ChannelErrorException - CHANNELERR occurred.

setSyncOnReturn

public void setSyncOnReturn(boolean syncOnReturn)
Control whether the program always performs a SYNCPOINT when it returns. This only applies to remote programs.


setTransId

public void setTransId(java.lang.String TRANSID)
Set the transaction name to be used when running the program remotely, instead of CPMI.

Parameters:
TRANSID - The name of the transaction to use. The transaction must be defined to run the same program as the CPMI transaction.

xctl

public void xctl()
          throws NotAuthorisedException,
                 InvalidProgramIdException
Transfer control to the program, terminating the current program.

Throws:
NotAuthorisedException - NOTAUTH occurred.
InvalidProgramIdException - PGMIDERR occurred.

xctl

public void xctl(byte[] CA)
          throws NotAuthorisedException,
                 InvalidProgramIdException
Transfer control to the program, terminating the current program, passing in a COMMAREA.

Parameters:
CA - A byte[] that is the COMMAREA to be passed.
Throws:
NotAuthorisedException - NOTAUTH occurred.
InvalidProgramIdException - PGMIDERR occurred.

xctl

public void xctl(Channel chan)
          throws NotAuthorisedException,
                 ChannelErrorException,
                 InvalidProgramIdException
Transfer control to the program, terminating the current program, passing a CHANNEL.

Parameters:
chan - A reference to the Channel to be passed
Throws:
NotAuthorisedException - NOTAUTH occurred.
InvalidProgramIdException - PGMIDERR occurred.
ChannelErrorException - CHANNELERR occurred.