com.ibm.cics.server
Class Task

java.lang.Object
  |
  +--com.ibm.cics.server.API
        |
        +--com.ibm.cics.server.Task
All Implemented Interfaces:
RetrieveBits

public class Task
extends API
implements RetrieveBits

This class provides a set of methods and variables that correspond to a CICS task.


Field Summary
 java.io.PrintWriter err
          A PrintWriter which is directed at the user's terminal, if the Principal Facility is a terminal, or to System.err if it is not.
static byte FCI_START_NO_DATA
           
static byte FCI_START_WITH_DATA
           
static byte FCI_TASK_WITH_FACILITY
           
static byte FCI_TRIGGERED_NO_FACILITY
           
 java.io.PrintWriter out
          A PrintWriter which is directed at the user's terminal, if the Principal Facility is a terminal, or to System.out if it is not.
 
Fields inherited from interface com.ibm.cics.server.RetrieveBits
DATA, NUMBER_OF_BITS, QUEUE, RTERMID, RTRANSID
 
Method Summary
 void abend(java.lang.String abcode)
          Request a normal ABEND of the task.
 void commit()
          Commit the work done as part of the task.
 void disableTaskTrace()
          Switch off task trace flag (Method is not supported in this release of CICS TS)
 void enableTaskTrace()
          Switch on task trace flag (Method is not supported in this release of CICS TS)
 void forceAbend(java.lang.String abcode)
          Force the task to ABEND.
 byte getFCI()
          Return the FCI for the task.
 java.lang.Object getPrincipalFacility()
          Return the principal facility for the current task.
 java.lang.String getProgramName()
          Return the CICS PROGRAM name.
 java.lang.String getQNAME()
          Return the QNAME for the task.
 java.lang.String getSTARTCODE()
          Return the STARTCODE for the task.
static Task getTask()
          Return the Task object representing the task as part of which the current thread is executing.
 int getTaskNumber()
          Return the task number.
 java.lang.String getTransactionName()
          Return the transaction name.
 void getTWA(TWAHolder holder)
          Return a copy of the Task Work Area (TWA).
 java.lang.String getUSERID()
          Return the USERID that is signed on to the task's principal facility.
 void retrieve(java.util.BitSet whatToRetrieve, RetrievedDataHolder holder)
          Retrieve any data specified when this task was started.
 void rollback()
          Roll back the work done as part of the task.
 void setTWA(byte[] data)
          Update the contents of the TWA from an array of bytes.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

err

public java.io.PrintWriter err
A PrintWriter which is directed at the user's terminal, if the Principal Facility is a terminal, or to System.err if it is not.

out

public java.io.PrintWriter out
A PrintWriter which is directed at the user's terminal, if the Principal Facility is a terminal, or to System.out if it is not.

FCI_START_NO_DATA

public static final byte FCI_START_NO_DATA

FCI_TASK_WITH_FACILITY

public static final byte FCI_TASK_WITH_FACILITY

FCI_TRIGGERED_NO_FACILITY

public static final byte FCI_TRIGGERED_NO_FACILITY

FCI_START_WITH_DATA

public static final byte FCI_START_WITH_DATA
Method Detail

abend

public void abend(java.lang.String abcode)
Request a normal ABEND of the task. This is the equivalent of an EXEC CICS ABEND command.

commit

public void commit()
            throws InvalidRequestException,
                   RolledBackException
Commit the work done as part of the task.
Throws:
InvalidRequestException - The program issuing the commit request is a remotely-linked-to program and SYNCONRETURN was not specified.
RolledBackException - The commit request could not be successfully completed and the current LUW has been rolled back.

disableTaskTrace

public void disableTaskTrace()
Switch off task trace flag (Method is not supported in this release of CICS TS)

enableTaskTrace

public void enableTaskTrace()
Switch on task trace flag (Method is not supported in this release of CICS TS)

forceAbend

public void forceAbend(java.lang.String abcode)
Force the task to ABEND. This is the equivalent of an EXEC CICS ABEND CANCEL command.

getFCI

public byte getFCI()
Return the FCI for the task.
Returns:
a byte containing the FCI.

getPrincipalFacility

public java.lang.Object getPrincipalFacility()
Return the principal facility for the current task.
Returns:
The principal facility (which may be null if there is no principal facility associated with the task). Note that it is a simple object reference which is returned. To decide if the principal facility is a terminal or a conversation, it is necessary to use the instanceof operator to test if the object reference returned is an instance of a Terminal or of a Conversation.

getQNAME

public java.lang.String getQNAME()
Return the QNAME for the task.
Returns:
a String containing the QNAME.

getSTARTCODE

public java.lang.String getSTARTCODE()
Return the STARTCODE for the task.
Returns:
a String containing the STARTCODE.

getTask

public static Task getTask()
Return the Task object representing the task as part of which the current thread is executing.
Returns:
a reference to the Task object.

getTaskNumber

public int getTaskNumber()
Return the task number.
Returns:
a int containing the task number.

getTransactionName

public java.lang.String getTransactionName()
Return the transaction name.
Returns:
a String containing the transaction name.

getTWA

public void getTWA(TWAHolder holder)
Return a copy of the Task Work Area (TWA).

The corresponding setTWA(byte[]) method must be called before returning from the task or invoking another program, as the Java TWA is a copy of the "real" TWA and any changes made in Java code must be reflected back into the "real" TWA before another program is invoked which would not see the current program's copy of the TWA.

Parameters:
a - holder for the TWA. If there is no TWA defined for the transaction, a byte[] of length 0 is returned as the value of the holder.

getUSERID

public java.lang.String getUSERID()
                           throws InvalidRequestException
Return the USERID that is signed on to the task's principal facility.
Returns:
a byte containing the USERID.
Throws:
InvalidRequestException - an INVREQ condition occurred

getProgramName

public java.lang.String getProgramName()
                                throws InvalidRequestException
Return the CICS PROGRAM name. This method is new in CICS TS 2.1.
Returns:
a String containing the program name.
Throws:
InvalidRequestException - an INVREQ condition occurred

retrieve

public void retrieve(java.util.BitSet whatToRetrieve,
                     RetrievedDataHolder holder)
              throws EndOfDataException,
                     InvalidRequestException,
                     InvalidRetrieveOptionException,
                     IOErrorException,
                     LengthErrorException,
                     RecordNotFoundException
Retrieve any data specified when this task was started.
Parameters:
whatToRetrieve - the RetrieveBits interface provides a set of constants that should be used to construct this java.util.BitSet
holder - for the RetrievedData
Throws:
EndOfDataException - a ENDDATA condition occurred
InvalidRequestException - an INVREQ condition occurred
InvalidRetrieveOptionException - a ENVDEFERR condition occurred
IOErrorException - an IOERR condition occurred
LengthErrorException - a LENGERR condition occurred
RecordNotFoundException - a NOTFND condition occurred

rollback

public void rollback()
              throws InvalidRequestException
Roll back the work done as part of the task.
Throws:
InvalidRequestException - The program issuing the commit request is a remotely-linked-to program and SYNCONRETURN was not specified.

setTWA

public void setTWA(byte[] data)
            throws InvalidRequestException
Update the contents of the TWA from an array of bytes.

This method must be called before returning from the task or invoking another program, as the Java TWA is a copy of the "real" TWA and any changes made in Java code must be reflected back into the "real" TWA before another program is invoked which would not see the current program's copy of the TWA.

Parameters:
data - the new data to be copied into the TWA.
Throws:
InvalidRequestException - the task does not have a TWA