com.ibm.cics.server
Class Task

java.lang.Object
  extended by com.ibm.cics.server.API
      extended by 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.

Author:
John Colgrave

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
          Constant - FCI_START_NO_DATA
static byte FCI_START_WITH_DATA
          Constant - FCI_START_WITH_DATA
static byte FCI_TASK_WITH_FACILITY
          Constant - FCI_TASK_WITH_FACILITY
static byte FCI_TRIGGERED_NO_FACILITY
          Constant - FCI_TRIGGERED_NO_FACILITY
static java.io.PrintWriter fixedErrForJVMLifetime
          STDERR
static java.io.PrintWriter fixedOutForJVMLifetime
          STDOUT
 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()
          Request a normal ABEND of the task with no ABEND code and no dump.
 void abend(java.lang.String abcode)
          Request a normal ABEND of the task with specific ABEND code.
 void abend(java.lang.String abcode, boolean dump)
          Request a normal ABEND of the task with specific ABEND code and optional dump.
 void commit()
          Commit the work done as part of the task.
 ContainerIterator containerIterator()
          Create a ContainerIterator for the current Channel.
 Channel createChannel(java.lang.String channelName)
          Create a Channel to hold the default number (16) of Containers.
 Channel createChannel(java.lang.String channelName, int listSize)
          Create a Channel with room for a specific number of Containers.
 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()
          Force the task to ABEND with no ABEND code and no dump.
 void forceAbend(java.lang.String abcode)
          Force the task to ABEND with a specific ABEND code and a dump.
 void forceAbend(java.lang.String abcode, boolean dump)
          Force the task to ABEND with a specific ABEND code and optional dump.
 Channel getChannel(java.lang.String channelName)
          Return the named Channel object if it matches the current channel's name or has been created through the JCICS API by this task earlier at this Link level.
 Channel getCurrentChannel()
          Return the current Channel, if any.
 boolean getDB2SQLJJDBCActive()
          Returns whether this Task is part of a DB2 SQLJ JDBC transaction.
 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.Thread getTaskThread()
          ->@L5A - Return the thread for the current task
 int getThreadPosition()
          Return the thread_position (index) into the DTC thread_control array
 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 setDB2SQLJJDBCActive(boolean active)
          Set/Reset the flag indicating that this Task is part of a DB2 SQLJ JDBC transaction.
 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.


fixedOutForJVMLifetime

public static java.io.PrintWriter fixedOutForJVMLifetime
STDOUT


fixedErrForJVMLifetime

public static java.io.PrintWriter fixedErrForJVMLifetime
STDERR


FCI_START_NO_DATA

public static final byte FCI_START_NO_DATA
Constant - FCI_START_NO_DATA

See Also:
Constant Field Values

FCI_TASK_WITH_FACILITY

public static final byte FCI_TASK_WITH_FACILITY
Constant - FCI_TASK_WITH_FACILITY

See Also:
Constant Field Values

FCI_TRIGGERED_NO_FACILITY

public static final byte FCI_TRIGGERED_NO_FACILITY
Constant - FCI_TRIGGERED_NO_FACILITY

See Also:
Constant Field Values

FCI_START_WITH_DATA

public static final byte FCI_START_WITH_DATA
Constant - FCI_START_WITH_DATA

See Also:
Constant Field Values
Method Detail

abend

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

Parameters:
abcode - the ABEND code

getTaskThread

public java.lang.Thread getTaskThread()
->@L5A - Return the thread for the current task

Returns:
a Thread containing the thread.

setDB2SQLJJDBCActive

public void setDB2SQLJJDBCActive(boolean active)
Set/Reset the flag indicating that this Task is part of a DB2 SQLJ JDBC transaction. Customers are not recommended to set this themselves.

Parameters:
active - , boolean set/reset

getDB2SQLJJDBCActive

public boolean getDB2SQLJJDBCActive()
Returns whether this Task is part of a DB2 SQLJ JDBC transaction.

Returns:
boolean active/not active

abend

public void abend(java.lang.String abcode,
                  boolean dump)
Request a normal ABEND of the task with specific ABEND code and optional dump. This is the equivalent of an EXEC CICS ABEND command.

Parameters:
abcode - the ABEND code
dump - false if NODUMP is required, else true

abend

public void abend()
Request a normal ABEND of the task with no ABEND code and no dump. This is the equivalent of an EXEC CICS ABEND command with no ABCODE specified, hence also NODUMP


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 with a specific ABEND code and a dump. This is the equivalent of an EXEC CICS ABEND CANCEL command with a dump.

Parameters:
abcode - the ABEND code

forceAbend

public void forceAbend(java.lang.String abcode,
                       boolean dump)
Force the task to ABEND with a specific ABEND code and optional dump. This is the equivalent of an EXEC CICS ABEND CANCEL command.

Parameters:
abcode - the ABEND code
dump - false if NODUMP is required, else true

forceAbend

public void forceAbend()
Force the task to ABEND with no ABEND code and no dump. This is the equivalent of an EXEC CICS ABEND CANCEL command with no ABCODE specified, hence also NODUMP


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.

getThreadPosition

public int getThreadPosition()
Return the thread_position (index) into the DTC thread_control array

Returns:
an int containing the index into the control_array

getCurrentChannel

public Channel getCurrentChannel()
Return the current Channel, if any.

Returns:
The current Channel for this task, or null if there is no current Channel

createChannel

public Channel createChannel(java.lang.String channelName)
                      throws ChannelErrorException
Create a Channel to hold the default number (16) of Containers. This is simply the initial List size, and will be increased if necessary.

Parameters:
channelName - the name of the new Channel
Returns:
The newly created Channel
Throws:
ChannelErrorException

createChannel

public Channel createChannel(java.lang.String channelName,
                             int listSize)
                      throws ChannelErrorException
Create a Channel with room for a specific number of Containers. If the number of Containers is known, this can be an optimization which can save storage or avoid having to automatically increase the List size.

Parameters:
channelName - the name of the new Channel
listSize - the initial number of Containers
Returns:
The newly created Channel
Throws:
ChannelErrorException

getChannel

public Channel getChannel(java.lang.String channelName)
Return the named Channel object if it matches the current channel's name or has been created through the JCICS API by this task earlier at this Link level.

Parameters:
String - channelName the name of the Channel to be returned; must not be null.
Returns:
The named Channel object if it exists, or null if it does not. The named channel will only be returned if it is the current channel, or if it was previously created using JCICS in this task at this link level.

containerIterator

public ContainerIterator containerIterator()
Create a ContainerIterator for the current Channel.

Returns:
A ContainerIterator for the current Channel, or null if there is no current Channel

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:
holder - 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