com.ibm.cics.server
Class StartRequest

java.lang.Object
  extended by com.ibm.cics.server.API
      extended by com.ibm.cics.server.Resource
          extended by com.ibm.cics.server.RemotableResource
              extended by com.ibm.cics.server.StartRequest
All Implemented Interfaces:
java.io.Serializable

public class StartRequest
extends RemotableResource
implements java.io.Serializable

This Bean provides the Java equivalent to the EXEC CICS START command.

In addition to the properties it inherits from RemotableResource, it defines the following properties:

transId
The name of the transaction to be started. This is the same as the name property inherited from Resource via RemotableResource.
time
A Calendar object which defines the time at which the task should be started.
ID
A name which is used as the name of a local Temporary Storage Queue.
terminal
A name which is used as the name of a local Terminal.
rTransaction
The name of the transaction that the started transaction will retrieve.
rTerminal
The name of the terminal that the started transaction will retrieve.
queueName
Specifies the name of a Temporary Storage Queue that may be used by the started transaction. If a name shorter than eight bytes is used it is padded to eight bytes.
checked
Indicates if CICS should provide full error checking and function. The default is true.
isProtected
A boolean which indicates if the start request is not to be processed until the task making the request has issued a SYNCPOINT. The default is false.

Version:
1.2
Author:
John Colgrave
See Also:
Serialized Form

Constructor Summary
StartRequest()
          Construct a StartRequest bean.
 
Method Summary
 void cancel()
          Cancel a previous start request
 byte[] getID()
          Return the ID that uniquely identifies the start request.
 java.lang.String getIDAsString()
          Return the ID that uniquely identifies the start request as a string, using the platform's default character encoding to convert from the byte[] format in which the name is stored.
 byte[] getQueueName()
          Return the queueName of the start request.
 java.lang.String getQueueNameAsString()
          Return the queue name of the start request as a string, using the platform's default character encoding to convert from the internal byte[] format in which the name is stored.
 java.lang.String getRTerminal()
          Get the name specified as the terminal name to be retrieved by the started task.
 java.lang.String getRTransaction()
          Get the name specified as the transaction name to be retrieved by the started task.
 java.lang.String getTerminal()
          Return the name of the terminal to be used as the principal facility of the started task.
 java.util.Calendar getTime()
          Return the time at which the task will be started.
 java.lang.String getTransId()
          Return the name of the Transaction to be started.
 boolean isChecked()
          Is this start request to be checked?
 boolean isProtected()
          Is this start request to be protected?
 void issue()
          Issue the start request passing no data to the started task.
 void issue(byte[] data)
          Issue the start request, passing a byte array to the started task.
 void issue(Channel chan)
          Issue the start request, passing a Channel to the started task.
 void setChecked(boolean checked)
          Control whether start request is checked or not.
 void setID(byte[] id)
          Set the ID that uniquely identifies the start request.
 void setIDFromString(java.lang.String id)
          Set the ID that uniquely identifies the start request from a String.
 void setProtected(boolean isProtected)
          Control whether start request is protected or not.
 void setQueueName(byte[] queueName)
          Sets the queueName of the start request.
 void setQueueNameFromString(java.lang.String name)
          Sets the queue name of the start request.
 void setRTerminal(java.lang.String rTerminal)
          Set the terminal name to be retrieved by the started task.
 void setRTransaction(java.lang.String rTransaction)
          Set the transaction name to be retrieved by the started task.
 void setTerminal(java.lang.String terminal)
          Set the name of the terminal to be used as the principal facility of the started task.
 void setTime(java.util.Calendar calendar)
          Set the time at which the task will be started.
 void setTransId(java.lang.String transId)
          Set the name of the Transaction to be started.
 
Methods inherited from class com.ibm.cics.server.RemotableResource
getSysId, setSysId
 
Methods inherited from class com.ibm.cics.server.Resource
getDescription, getName, setDescription, setName
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

StartRequest

public StartRequest()
Construct a StartRequest bean.

Method Detail

cancel

public void cancel()
            throws InvalidRequestException,
                   ISCInvalidRequestException,
                   NotAuthorisedException,
                   RecordNotFoundException,
                   InvalidSystemIdException
Cancel a previous start request

Throws:
InvalidRequestException - INVREQ occurred.
ISCInvalidRequestException - ISCINVREQ occurred.
NotAuthorisedException - NOTAUTH occurred.
RecordNotFoundException - NOTFND occurred.
InvalidSystemIdException - SYSIDERR occurred.

setTransId

public void setTransId(java.lang.String transId)
Set the name of the Transaction to be started.

Parameters:
transId - Transaction to be started

getID

public byte[] getID()
Return the ID that uniquely identifies the start request.

Returns:
String the ID of the start request.

getIDAsString

public java.lang.String getIDAsString()
Return the ID that uniquely identifies the start request as a string, using the platform's default character encoding to convert from the byte[] format in which the name is stored.

Returns:
String the ID of the start request.

getQueueName

public byte[] getQueueName()
Return the queueName of the start request.

Returns:
byte[] the start request queueName

getQueueNameAsString

public java.lang.String getQueueNameAsString()
Return the queue name of the start request as a string, using the platform's default character encoding to convert from the internal byte[] format in which the name is stored.

Returns:
String the TSQ name

getRTerminal

public java.lang.String getRTerminal()
Get the name specified as the terminal name to be retrieved by the started task.

Returns:
the name

getRTransaction

public java.lang.String getRTransaction()
Get the name specified as the transaction name to be retrieved by the started task.

Returns:
the name

getTerminal

public java.lang.String getTerminal()
Return the name of the terminal to be used as the principal facility of the started task.

Returns:
the name of the terminal

getTime

public java.util.Calendar getTime()
Return the time at which the task will be started.

Returns:
Calendar a Calendar object for the current default locale which indicates the time at which the task will be started.

getTransId

public java.lang.String getTransId()
Return the name of the Transaction to be started.

Returns:
String transId Transaction to be started

isChecked

public boolean isChecked()
Is this start request to be checked?

Returns:
true if it is to be checked, false otherwise.

isProtected

public boolean isProtected()
Is this start request to be protected?

Returns:
true if it is to be protected, false otherwise.

issue

public void issue()
           throws InvalidRequestException,
                  ISCInvalidRequestException,
                  IOErrorException,
                  LengthErrorException,
                  NotAuthorisedException,
                  InvalidSystemIdException,
                  TerminalException,
                  InvalidTransactionIdException
Issue the start request passing no data to the started task.

Throws:
InvalidRequestException - INVREQ occurred.
ISCInvalidRequestException - ISCINVREQ occurred.
IOErrorException - IOERR occurred.
LengthErrorException - LENGERR occurred.
NotAuthorisedException - NOTAUTH occurred.
InvalidSystemIdException - SYSIDERR occurred.
TerminalException - TERMERR occurred.
InvalidTransactionIdException - TRANSIDERR occurred.

issue

public void issue(byte[] data)
           throws InvalidRequestException,
                  ISCInvalidRequestException,
                  IOErrorException,
                  LengthErrorException,
                  NotAuthorisedException,
                  InvalidSystemIdException,
                  TerminalException,
                  InvalidTransactionIdException
Issue the start request, passing a byte array to the started task.

Parameters:
data - A byte[] that is the data to be passed to the started task.
Throws:
InvalidRequestException - INVREQ occurred.
ISCInvalidRequestException - ISCINVREQ occurred.
IOErrorException - IOERR occurred.
LengthErrorException - LENGERR occurred.
NotAuthorisedException - NOTAUTH occurred.
InvalidSystemIdException - SYSIDERR occurred.
TerminalException - TERMERR occurred.
InvalidTransactionIdException - TRANSIDERR occurred.

issue

public void issue(Channel chan)
           throws InvalidRequestException,
                  ISCInvalidRequestException,
                  IOErrorException,
                  LengthErrorException,
                  NotAuthorisedException,
                  InvalidSystemIdException,
                  TerminalException,
                  InvalidTransactionIdException,
                  ChannelErrorException
Issue the start request, passing a Channel to the started task.

Parameters:
chan - A Channel that is the channel to be passed to the started task.
Throws:
InvalidRequestException - INVREQ occurred.
ISCInvalidRequestException - ISCINVREQ occurred.
IOErrorException - IOERR occurred.
LengthErrorException - LENGERR occurred.
NotAuthorisedException - NOTAUTH occurred.
InvalidSystemIdException - SYSIDERR occurred.
TerminalException - TERMERR occurred.
InvalidTransactionIdException - TRANSIDERR occurred.
ChannelErrorException - CHANNELERR occurred.

setChecked

public void setChecked(boolean checked)
Control whether start request is checked or not.

Parameters:
checked - true means request is checked; false means it is not.

setID

public void setID(byte[] id)
Set the ID that uniquely identifies the start request. If the id passed in is shorter than 8 bytes it is padded to 8 bytes with bytes containing 0x00.

Parameters:
id - The unique name. Its length should be <= 8.
Throws:
java.lang.NullPointerException - start id is null

setIDFromString

public void setIDFromString(java.lang.String id)
Set the ID that uniquely identifies the start request from a String.

Parameters:
id - The unique name. If the length of the String is less than eight it is padded to 8 characters using space characters and it is then converted to bytes using the platform's default encoding. If the length of the resulting byte array is more than eight then it is truncated to exactly eight bytes.
Throws:
java.lang.NullPointerException - start id is null

setProtected

public void setProtected(boolean isProtected)
Control whether start request is protected or not.

Parameters:
isProtected - true means request is protected; false means it is not.

setQueueName

public void setQueueName(byte[] queueName)
                  throws java.lang.NullPointerException
Sets the queueName of the start request.

Parameters:
queueName - the queueName of the start request. If the length of the queue name is less than eight it is padded with the hex value of blank in the platform's default character encoding. Over-length queueNames will be truncated.
Throws:
java.lang.NullPointerException - queueName is null

setQueueNameFromString

public void setQueueNameFromString(java.lang.String name)
                            throws java.lang.NullPointerException
Sets the queue name of the start request.

Parameters:
name - the queue name of the start request as a string. If the length of the String is less than eight it is padded to 8 characters using space characters and it is then converted to bytes using the platform's default encoding. If the length of the resulting byte array is more than eight then it is truncated to exactly eight bytes.
Throws:
java.lang.NullPointerException - queueName is null

setRTerminal

public void setRTerminal(java.lang.String rTerminal)
Set the terminal name to be retrieved by the started task.

Parameters:
rTerminal - the terminal name.

setRTransaction

public void setRTransaction(java.lang.String rTransaction)
Set the transaction name to be retrieved by the started task.

Parameters:
rTransaction - the transaction name.

setTerminal

public void setTerminal(java.lang.String terminal)
Set the name of the terminal to be used as the principal facility of the started task.

Parameters:
terminal - the name of the terminal

setTime

public void setTime(java.util.Calendar calendar)
Set the time at which the task will be started.

Parameters:
calendar - A Calendar object for the time at which the task is to be started.