com.ibm.ims.application
Class IMSTransaction

java.lang.Object
  |
  +--com.ibm.ims.application.IMSTransaction

public final class IMSTransaction
extends java.lang.Object

The IMSTransaction class provides Java Dependent Region programs access to IMS transaction services such as commit and rollback. A singleton IMSTransaction object is returned to an application for use by calling the static IMSTransaction method getTransaction. All transactions using IMS Transaction Services are done with global scope.


Method Summary
 void abend()
          Abnormally terminates the application by making a "ROLL" call.
 void checkpoint()
          Performs a checkpoint call for a JBP application that uses symbolic checkpoints.
 void checkpoint(SaveArea saveArea)
          Performs a checkpoint call for a JBP application that uses symbolic checkpoints.
 void checkpoint(java.lang.String chkpId)
          Performs a checkpoint call for a JBP application that uses symbolic checkpoints.
 void checkpoint(java.lang.String chkpId, SaveArea saveArea)
          Performs a checkpoint call for a JBP application that uses symbolic checkpoints.
 void commit()
          Commits the transaction and cleans up the resources.
static IMSTransaction getTransaction()
          Returns the singleton IMSTransaction object.
 SaveArea restart()
          Performs an XRST call for a JBP application that uses symbolic checkpoints.
 SaveArea restart(java.lang.String id)
          Performs an XRST call for a JBP application that uses symbolic checkpoints.
 void rollback()
          Rolls back the transaction and cleans up the resources by making a ROLB call.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

abend

public void abend()
Abnormally terminates the application by making a "ROLL" call. It backs out the output messages sent by the conversational application program.
Parameters:
exception - -- the exception that causes the program to abend.

commit

public void commit()
            throws IMSException
Commits the transaction and cleans up the resources. It invokes the JDBC driver commit method to clean up the JDBC/SQLJ resources.
Throws:
IMSException - if a non-blank status code is returned from the system call or if the call to JDBC commit failed.

rollback

public void rollback()
              throws IMSException
Rolls back the transaction and cleans up the resources by making a ROLB call. This undoes any database work done from the IMS Application including work done using the DB2 driver and messages sent or received from the Message Queue.
Throws:
IMSException - if a non-blank status code is returned from the system call or if the call to JDBC rollback failed.

getTransaction

public static IMSTransaction getTransaction()
Returns the singleton IMSTransaction object.
Returns:
an IMSTransaction object

checkpoint

public void checkpoint()
                throws IMSException

Performs a checkpoint call for a JBP application that uses symbolic checkpoints. If the program uses symbolic checkpoint/restart, it calls this function at intervals to cause checkpoints to be written to the IMS log.

This version of the checkpoint method does not take any parameters. This should be used in the cases where the application needs to take checkpoints without having to specify a checkpoint ID and also without having to save any application objects. When using this method for taking checkpoints, the application should use the 4-character constant "LAST" as the checkpoint ID to restart from. If the application needs to save application objects, it should use one of the other two forms of the checkpoint method:
checkpoint(SaveArea saveArea).
checkpoint(String chkpId, SaveArea saveArea).

If the application needs to specify a checkpoint ID, it should use one of the other two forms of the checkpoint method:
checkpoint(String chkpid).
checkpoint(String chkpId, SaveArea saveArea).

Before taking any checkpoints, the application must issue an initial IMSTransaction.restart() call to notify IMS that it intends to use symbolic checkpoints.

Parameters:
chkpId - Checkpoint ID to identify this checkpoint.
Throws:
IMSException - if the checkpoint ID is invalid, or if an IMS call returns a non-blank status code.

checkpoint

public void checkpoint(SaveArea saveArea)
                throws IMSException

Performs a checkpoint call for a JBP application that uses symbolic checkpoints. If the program uses symbolic checkpoint/restart, it calls this function at intervals to cause checkpoints to be written to the IMS log.

This should be used in the cases where the application needs to take checkpoints without having to specify a checkpoint ID. When using this method for taking checkpoints, the application should use the 4-character constant "LAST" as the checkpoint ID to restart from.
If the application needs to specify a checkpoint ID, it should use one of the other two forms of the checkpoint method:
checkpoint(String chkpid).
checkpoint(String chkpId, SaveArea saveArea).

Before taking any checkpoints, the application must issue an initial IMSTransaction.restart() call to notify IMS that it intends to use symbolic checkpoints.

Parameters:
chkpId - Checkpoint ID to identify this checkpoint.
Throws:
IMSException - if the checkpoint ID is invalid, or if an IMS call returns a non-blank status code.

checkpoint

public void checkpoint(java.lang.String chkpId)
                throws IMSException

Performs a checkpoint call for a JBP application that uses symbolic checkpoints. If the program uses symbolic checkpoint/restart, it calls this function at intervals to cause checkpoints to be written to the IMS log.

This version of the checkpoint method does not save any application objects with the checkpoint. If the application needs to save application objects, it should use the other form of the checkpoint method, checkpoint(String chkpId, SaveArea saveArea).

The only parameter accepted by this function is an application-provided checkpoint ID between 1 and 8 characters in length.

Before taking any checkpoints, the application must issue an initial IMSTransaction.restart() call to notify IMS that it intends to use symbolic checkpoints.

Parameters:
chkpId - Checkpoint ID to identify this checkpoint.
Throws:
IMSException - if the checkpoint ID is invalid, or if an IMS call returns a non-blank status code.

checkpoint

public void checkpoint(java.lang.String chkpId,
                       SaveArea saveArea)
                throws IMSException

Performs a checkpoint call for a JBP application that uses symbolic checkpoints. If the program uses symbolic checkpoint/restart, it calls this function at intervals to checkpoint selected objects to the IMS log.

This method saves applicaiton objects with the checkpoint ID.

The first parameter required by this function is an application-provided checkpoint ID between 1 and 8 characters in length. The second parameter is a SaveArea object that contains one or more Java objects to be checkpointed. This method serialises and checkpoints the SaveArea object and its contained objects to the IMS log. The order in which the objects are held in this SaveArea object will determine the order in which they are returned by a later restart() call.

This checkpoint method also checks the length of the serialized data against the maximum allowable length defined in the static SaveArea class variable checkpointSizeLimit. If it exceeds this limit, an exception is thrown. The application then needs to be re-run after it increases the limit by calling the SaveArea.setCheckpointSizeLimit() method, and re-run the application from the most recent valid checkpoint.

Before taking any checkpoints, the application must issue an initial IMSTransaction.restart() call to notify IMS that it intends to use symbolic checkpoints.

Parameters:
chkpId - Checkpoint ID to identify this checkpoint.
saveArea - SaveArea object that contains objects to be saved.
Throws:
IMSException - thrown if
the SaveArea parameter has greater size than the maximum allowed as stored in the SaveArea class variable, checkpointSizeLimit, or
if the checkpoint ID is null or has incorrect length.

restart

public SaveArea restart()
                 throws IMSException

Performs an XRST call for a JBP application that uses symbolic checkpoints.

This method is used by an application in the following situations:
1. At normal program start, this method tells IMS that subsequent checkpoint calls are symbolic checkpoint calls.
2. The restart checkpoint ID (if any) is supplied through the CKPTID= parameter in the JBP region JCL procedure.

If the application needs to supply the restart checkpoint ID, use the restart(String id) method.

Returns:
the objects to be restored.
Throws:
IMSException - if a non-blank status code is returned from the XRST call.

restart

public SaveArea restart(java.lang.String id)
                 throws IMSException

Performs an XRST call for a JBP application that uses symbolic checkpoints. If the application program uses symbolic checkpoint/restart, it calls this method before issuing any checkpoint calls.

Note: An alternative is for the application to use the version of the restart() method that takes no parameters. This version should be used if restart checkpoint IDs are supplied by the CKPTID= parameter in the EXEC statement of the JBP region JCL procedure.

If this method is called at initial program start, the application must pass a null checkpoint ID String parameter. The restart ID in the JBP region JCL EXEC statement CKPTID= must also be null. On an initial start, with a null or absent restart ID, the call only notifies IMS that subsequent checkpoint calls will be symbolic. In this case, the restart call returns a null SaveArea reference because there are no checkpointed objects to return.

If the application is restarting from a checkpoint, pass a restart checkpoint ID from 1 to 14 bytes in the String ID parameter. If, the CKPTID= parameter in the EXEC statement of the JBP region JCL procedure is set, the id String parameter can be null. If the String ID parameter and the CKPTID= paramenter are set to a non-null value, the CKPTID= parameter in the EXEC statement takes precedence. When restarting from a checkpoint, the restart call returns the checkpointed objects from the IMS log in a SaveArea object. The checkpointed objects are returned in the same order in which they were saved by a checkpoint call. If no objects were saved by the checkpoint(String, SaveArea) call, a null reference is returned.

Parameters:
id - Checkpoint ID to restart from.
Returns:
null if this is a normal start or the SaveArea object stored before using symbolic checkpoints.
Throws:
IMSException. - if a non-blank status code is returned from the system call or if checkpoint id to restart from is of incorrect length.
IMSException - if a non-blank status code is returned from the XRST call or if the checkpoint ID to restart from is the wrong length


(C) International Business Machines Corporation 2004. All rights reserved.