com.ibm.cics.server
Class Task

java.lang.Object
  extended bycom.ibm.cics.server.API
      extended bycom.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
           
static byte FCI_START_WITH_DATA
           
static byte FCI_TASK_WITH_FACILITY
           
static byte FCI_TRIGGERED_NO_FACILITY
           
static java.io.PrintWriter fixedErrForJVMLifetime
           
static java.io.PrintWriter fixedOutForJVMLifetime
          Standard output and standard error can be redirected to two places by this class.
 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.
 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.


fixedOutForJVMLifetime

public static java.io.PrintWriter fixedOutForJVMLifetime
Standard output and standard error can be redirected to two places by this class. If you have a principal facility that is a terminal, then that the terminal may change each time a JVM is reused and so some reinitialization is necessary of the output and error streams. However, if there is no terminal then output and error go to the values set for the JVM when it was started - these are files opened by DFHSJCS when the JVM is starting for the first time, these files don't change. Therefore a simple optimization is to just do the setup for mapping java output streams to the HFS output streams once. So, that is what we do and they are cached in these two fields. Caching them in these fields rather than in out/err directly allows for a JVM that gets used for multiple types of task, some with terminal principal facilities, some not. If we use a terminal then out/err will be redirected to it, then when the next task runs without a terminal, we can quickly set out/err to these cached values rather than rebuilding them from scratch. 'The third way' With CICS TS 2.3, out/err can be redirected to different places using the output redirection class that can be passed from the JVM profile. The wrapper handles this redirection separately - in this case, the caching here is useless. This 'third' kind of redirection will introduce poor performance due to the inability to cache reuable information - but this flexibility in redirection is intended for application development where a group of users are sharing a JVM pool and want their own output locations.


fixedErrForJVMLifetime

public static java.io.PrintWriter fixedErrForJVMLifetime

FCI_START_NO_DATA

public static final byte FCI_START_NO_DATA
See Also:
Constant Field Values

FCI_TASK_WITH_FACILITY

public static final byte FCI_TASK_WITH_FACILITY
See Also:
Constant Field Values

FCI_TRIGGERED_NO_FACILITY

public static final byte FCI_TRIGGERED_NO_FACILITY
See Also:
Constant Field Values

FCI_START_WITH_DATA

public static final byte 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.


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.


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.


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.


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.

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.

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.

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.

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.


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