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.

Since CICS TS version:
1.3
Since package version:
1.0

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()
          Deprecated. in 4.2
 void enableTaskTrace()
          Deprecated. in 4.2
 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()
          Return the thread for the current task
 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.

Since CICS TS version:
1.3
Since package version:
1.0

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.

Since CICS TS version:
1.3
Since package version:
1.0

fixedOutForJVMLifetime

public static java.io.PrintWriter fixedOutForJVMLifetime
STDOUT

Since CICS TS version:
2.3
Since package version:
1.0

fixedErrForJVMLifetime

public static java.io.PrintWriter fixedErrForJVMLifetime
STDERR

Since CICS TS version:
2.3
Since package version:
1.0

FCI_START_NO_DATA

public static final byte FCI_START_NO_DATA
Constant - FCI_START_NO_DATA

See Also:
Constant Field Values
Since CICS TS version:
1.3
Since package version:
1.0

FCI_TASK_WITH_FACILITY

public static final byte FCI_TASK_WITH_FACILITY
Constant - FCI_TASK_WITH_FACILITY

See Also:
Constant Field Values
Since CICS TS version:
1.3
Since package version:
1.0

FCI_TRIGGERED_NO_FACILITY

public static final byte FCI_TRIGGERED_NO_FACILITY
Constant - FCI_TRIGGERED_NO_FACILITY

See Also:
Constant Field Values
Since CICS TS version:
1.3
Since package version:
1.0

FCI_START_WITH_DATA

public static final byte FCI_START_WITH_DATA
Constant - FCI_START_WITH_DATA

See Also:
Constant Field Values
Since CICS TS version:
1.3
Since package version:
1.0
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
Since CICS TS version:
1.3
Since package version:
1.0

getTaskThread

public java.lang.Thread getTaskThread()
Return the thread for the current task

Returns:
a Thread containing the thread.
Since CICS TS version:
4.1
Since package version:
1.201

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
Since CICS TS version:
4.2
Since package version:
1.300

getDB2SQLJJDBCActive

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

Returns:
boolean active/not active
Since CICS TS version:
4.2
Since package version:
1.300

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
Since CICS TS version:
3.1
Since package version:
1.0

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

Since CICS TS version:
3.1
Since package version:
1.0

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.
Since CICS TS version:
1.3
Since package version:
1.0

disableTaskTrace

@Deprecated
public void disableTaskTrace()
Deprecated. in 4.2

Switch off task trace flag

Since CICS TS version:
1.3
Since package version:
1.0

enableTaskTrace

@Deprecated
public void enableTaskTrace()
Deprecated. in 4.2

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

Since CICS TS version:
1.3
Since package version:
1.0

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
Since CICS TS version:
1.3
Since package version:
1.0

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
Since CICS TS version:
3.1
Since package version:
1.0

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

Since CICS TS version:
3.1
Since package version:
1.0

getFCI

public byte getFCI()
Return the FCI for the task.

Returns:
a byte containing the FCI.
Since CICS TS version:
1.3
Since package version:
1.0

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.
Since CICS TS version:
1.3
Since package version:
1.0

getQNAME

public java.lang.String getQNAME()
Return the QNAME for the task.

Returns:
a String containing the QNAME.
Since CICS TS version:
1.3
Since package version:
1.0

getSTARTCODE

public java.lang.String getSTARTCODE()
Return the STARTCODE for the task.

Returns:
a String containing the STARTCODE.
Since CICS TS version:
1.3
Since package version:
1.0

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
Since CICS TS version:
3.1
Since package version:
1.0

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 - CHANNELERR
Since CICS TS version:
3.1
Since package version:
1.0

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 - CHANNELERR
Since CICS TS version:
3.1
Since package version:
1.0

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:
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.
Since CICS TS version:
3.2
Since package version:
1.100

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
Since CICS TS version:
3.1
Since package version:
1.0

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.
Since CICS TS version:
1.3
Since package version:
1.0

getTaskNumber

public int getTaskNumber()
Return the task number.

Returns:
a int containing the task number.
Since CICS TS version:
1.3
Since package version:
1.0

getTransactionName

public java.lang.String getTransactionName()
Return the transaction name.

Returns:
a String containing the transaction name.
Since CICS TS version:
1.3
Since package version:
1.0

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.
Since CICS TS version:
1.3
Since package version:
1.0

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
Since CICS TS version:
1.3
Since package version:
1.0

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
Since CICS TS version:
2.1
Since package version:
1.0

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
Since CICS TS version:
1.3
Since package version:
1.0

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.
Since CICS TS version:
1.3
Since package version:
1.0

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
Since CICS TS version:
1.3
Since package version:
1.0