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.
- See Also:
com.ibm.cics.server.API
for general restrictions on using the JCICS API.- Since CICS TS version:
- 1.3
- Since package version:
- 1.0
-
-
Field Summary
Fields Modifier and Type Field and Description 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_DATAstatic byte
FCI_START_WITH_DATA
Constant - FCI_START_WITH_DATAstatic byte
FCI_TASK_WITH_FACILITY
Constant - FCI_TASK_WITH_FACILITYstatic byte
FCI_TRIGGERED_NO_FACILITY
Constant - FCI_TRIGGERED_NO_FACILITYstatic java.io.PrintWriter
fixedErrForJVMLifetime
STDERRstatic java.io.PrintWriter
fixedOutForJVMLifetime
STDOUTjava.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
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method and Description 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.2void
enableTaskTrace()
Deprecated.in 4.2void
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.ApplicationContext
getApplicationContext()
Return the Application Context.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.String
getInvokingProgramName()
Return the Invoking program name.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 theTask
object representing the task as part of which the current thread is executing.int
getTaskNumber()
Return the task number.java.lang.Integer
getTaskNumberInteger()
Return the task number as an Integer.java.lang.Thread
getTaskThread()
Return the thread for the current taskjava.lang.String
getThreadName()
Get the name of the Java thread in the JVM server that corresponds to this Task If the task has a current program this will be: program_name.TASKtask_number.transaction_name otherwise it will be TASKtask_number.transaction_nameChannel
getTransactionChannel()
Return the transaction Channel, if any.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.boolean
isJTATranActive()
Determines whether this Task is running under the context of a UserTransaction within the Java Transaction API (JTA)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
setJTATranActive(boolean setJTATran)
setJTATranActivevoid
setTWA(byte[] data)
Update the contents of the TWA from an array of bytes.
-
-
-
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_FACILITYThis code indicates that the principal facility for the task is a terminal.
- 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_FACILITYThis code indicates that the principal facility for the task is a transient data queue.
- 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_DATAAID facility mask. This code is no longer in use.
- 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 codedump
- false if NODUMP is required, else true- Throws:
java.lang.IllegalArgumentException
- if abcode is null- 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, or a JTA Transaction is active.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.2Switch off task trace flag- Since CICS TS version:
- 1.3
- Since package version:
- 1.0
-
enableTaskTrace
@Deprecated public void enableTaskTrace()
Deprecated. in 4.2Switch 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 codedump
- 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 theinstanceof
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.Values:
'D' - A distributed program link (DPL) request that did not specify the SYNCONRETURN option. The task cannot issue I/O requests against its principal facility, or any sync point requests.
'DS' - A distributed program link (DPL) request, as in code D, that did specify the SYNCONRETURN option. The task can issue sync point requests.
'QD' - Transient data trigger level.
'S' - START command that did not pass data in the FROM option. It might or might not have passed a channel.
'SD' - START command that passed data in the FROM option.
'SZ' - FEPI START command.
'TD' - Terminal input or permanent transid.
'U' - User-attached task. - Since CICS TS version:
- 1.3
- Since package version:
- 1.0
-
getTransactionChannel
public Channel getTransactionChannel()
Return the transaction Channel, if any.- Returns:
- The transaction Channel for this task
- Since CICS TS version:
- 5.2
- Since package version:
- 1.500
-
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 ChannellistSize
- 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 theTask
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
-
getTaskNumberInteger
public java.lang.Integer getTaskNumberInteger()
Return the task number as an Integer.- Returns:
- an
Integer
containing the task number. - Since CICS TS version:
- 5.3
- Since package version:
- 1.600.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()
Return the CICS PROGRAM name. This method replaces the old method as PROGRAMNAME is now part of task class data- Returns:
- a
String
containing the program name. - Since CICS TS version:
- ts 5.2
-
getInvokingProgramName
public java.lang.String getInvokingProgramName()
Return the Invoking program name.- Returns:
- a
String
containing the invoking program. - Since CICS TS version:
- ts 5.3
-
getApplicationContext
public ApplicationContext getApplicationContext() throws InvalidRequestException
Return the Application Context. This method is new in CICS TS 5.2.- Returns:
- a
ApplicationContext
containing the current application context for this transaction. - Throws:
InvalidRequestException
- an INVREQ condition occurred- Since CICS TS version:
- 5.2
- Since package version:
- 1.501
-
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 thisjava.util.BitSet
holder
- for the RetrievedData- Throws:
EndOfDataException
- a ENDDATA condition occurredInvalidRequestException
- an INVREQ condition occurredInvalidRetrieveOptionException
- a ENVDEFERR condition occurredIOErrorException
- an IOERR condition occurredLengthErrorException
- a LENGERR condition occurredRecordNotFoundException
- 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 or a JTA UserTransaction is active.- 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
-
setJTATranActive
public void setJTATranActive(boolean setJTATran)
setJTATranActiveThis method is used to indicate that a JTA UserTransaction has been started or ended. When a JTA UserTransaction is active, the DTC Task.commit() and Task.rollback() methods cannot be used. Customers are not recommended to set this themselves.
- Parameters:
setJTATran
- true or false- Since CICS TS version:
- 5.2
-
getThreadName
public java.lang.String getThreadName()
Get the name of the Java thread in the JVM server that corresponds to this Task If the task has a current program this will be: program_name.TASKtask_number.transaction_name otherwise it will be TASKtask_number.transaction_name- Returns:
- the thread name
-
isJTATranActive
public boolean isJTATranActive()
Determines whether this Task is running under the context of a UserTransaction within the Java Transaction API (JTA)- Returns:
- true or false
-
-