CICS® Transaction Gateway Programming Reference v1.1.0.0

com.ibm.ctg.epi
Class Terminal

java.lang.Object
  extended by com.ibm.ctg.epi.Terminal
All Implemented Interfaces:
EPIEndReasonCodes, TerminalInterface, TerminalSession, java.io.Serializable

public class Terminal
extends java.lang.Object
implements TerminalInterface, EPIEndReasonCodes, java.io.Serializable

This class represents an EPI terminal.

See Also:
TerminalSession, Serialized Form

Nested Class Summary
static class Terminal.EPISignOnType
          Class to allow for compile time checking of signon enumerations.
 
Field Summary
static Terminal.EPISignOnType EPI_SIGNON_CAPABLE
          Signon Capable enumeration.
static Terminal.EPISignOnType EPI_SIGNON_INCAPABLE
          Signon Incapable enumeration.
static Terminal.EPISignOnType EPI_SIGNON_UNKNOWN
          Signon Unknown enumeration, do not use to try to create a terminal.
 
Fields inherited from interface com.ibm.ctg.epi.TerminalSession
client, discon, error, failed, idle, server, start, txnTimedOut
 
Fields inherited from interface com.ibm.ctg.client.EPIEndReasonCodes
astrEndReason, EPI_END_FAILED, EPI_END_OUTSERVICE, EPI_END_SHUTDOWN, EPI_END_SIGNOFF, EPI_END_UNKNOWN, EPI_READTIMEOUT_EXPIRED, EPI_TRAN_NO_ERROR, EPI_TRAN_NOT_STARTED, EPI_TRAN_STATE_UNKNOWN, strINVALID_END_REASON
 
Constructor Summary
Terminal()
          Constructs a terminal which must be connected to a Java Gateway before it can be used.
Terminal(JavaGateway jgate, java.lang.String server, java.lang.String devtype, java.lang.String netname)
          Constructs a basic terminal to the given server using the given gateway and automatically connects the terminal.
Terminal(JavaGateway jgate, java.lang.String server, java.lang.String devtype, java.lang.String netname, Terminal.EPISignOnType signoncapability, java.lang.String userid, java.lang.String password, int readtimeout, java.lang.String encoding)
          Constructs an extended terminal to the given server using the given gateway which must be connected to explicitly before it can be used.
 
Method Summary
 EPISecurityAttrs changePassword(java.lang.String newPass)
          Allows you to change the password for a given user ID and current password with the External Security Manager.
 void connect()
          Connects a basic or extended terminal to the server.
 void connect(int installtimeout)
          Connects an extended terminal to the CICS server.
 void connect(Session session, int installtimeout)
          Connects an extended terminal to the CICS server.
 void disconnect()
          Disconnects the terminal from the server.
 java.lang.String getDeviceType()
          Returns the device type of the terminal, or the device type to be used if the terminal is not currently connected.
 java.lang.String getEncoding()
          Returns the current encoding used for a connected extended terminal or the encoding to be used if an extended terminal is not connected.
 int getEndReason()
          Returns the end reason code.
 java.lang.String getEndReasonString()
          Returns the end reason code as a string.
 int getInstallTimeout()
          Returns the install timeout associated with this terminal.
 java.lang.String getNetName()
          Returns the netname of the terminal, or the netname to be used if the terminal is not currently connected.
 java.lang.String getPassword()
          Returns the password associated with the terminal, or null if the password is null or the terminal is a basic terminal.
 int getReadTimeout()
          Returns the read timeout associated with this terminal or the read timeout to be set if the terminal is not connected.
 Screen getScreen()
          Returns the screen associated with the terminal.
 java.lang.String getServerName()
          Returns the name of the server the terminal is connected to, or will be connected to if the terminal is not currently connected.
 Terminal.EPISignOnType getSignonCapability()
          If the terminal is connected, the signon capability of the associated EPI terminal is returned.
 java.lang.String getSignonString()
          Gets the Signon Capability set in this object and return it as a string.
 int getState()
          Returns the state of the terminal as defined in TerminalSession.
 java.lang.String getTermid()
          Returns the terminal ID associated with the terminal.
 java.lang.String getTransID()
          Returns the transaction ID of the current transaction.
 java.lang.String getUserid()
          Returns the user ID associated with the terminal, or null if the user ID is null or the terminal is a basic terminal.
 boolean isExtendedTerminal()
          Returns whether the connected terminal is extended or not, or the type of terminal that will be requested if not connected.
 boolean isPurgeOnDisconnect()
          Returns the purgeOnDisconnect flag for this terminal.
 boolean queryATI()
          Returns a boolean indicating whether the terminal ATI state is enabled or disabled.
 void send()
          Sends the current screen to the server using the current session.
 void send(Session session)
          Sends the current screen to the server.
 void send(Session session, java.lang.String transid, java.lang.String data)
          Starts a transaction on the server.
 void send(java.lang.String transid, java.lang.String data)
          Starts a transaction on the server using the current session.
 void setATI(boolean on)
          Sets the terminal ATI state to be enabled or disabled.
 void setDeviceType(java.lang.String devtype)
          Sets the device type the terminal should use.
 void setEncoding(java.lang.String newEncoding)
          Sets the Java Encoding associated with the terminal.
 void setExtendedTerminal(boolean flag)
          Sets whether this terminal is an extended terminal or not.
 void setGateway(JavaGateway jgate)
          Sets the Java Gateway that this terminal should use to connect to the server.
 void setInstallTimeout(int installtimeout)
          Sets the install timeout associated with the terminal.
 void setNetName(java.lang.String netname)
          Sets the netname that terminal should use.
 void setPassword(java.lang.String password)
          Sets the password associated with the terminal.
 void setPurgeOnDisconnect(boolean flag)
          Sets whether a terminal will purge on disconnect or not.
 void setReadTimeout(int readtimeout)
          Sets the read timeout associated with the terminal.
 void setServerName(java.lang.String server)
          Sets the name of the server the terminal should connect to.
 void setSession(Session newSess)
          Set the Session object associated with the terminal.
 void setSignonCapability(Terminal.EPISignOnType signoncapability)
          Sets the signon capability associated with the terminal.
 void setUserid(java.lang.String newUserid)
          Sets the user ID associated with the terminal.
 EPISecurityAttrs verifyPassword()
          Verifies the user ID and password with the External Security Manager.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EPI_SIGNON_CAPABLE

public static final Terminal.EPISignOnType EPI_SIGNON_CAPABLE
Signon Capable enumeration.


EPI_SIGNON_INCAPABLE

public static final Terminal.EPISignOnType EPI_SIGNON_INCAPABLE
Signon Incapable enumeration.


EPI_SIGNON_UNKNOWN

public static final Terminal.EPISignOnType EPI_SIGNON_UNKNOWN
Signon Unknown enumeration, do not use to try to create a terminal.

Constructor Detail

Terminal

public Terminal()
Constructs a terminal which must be connected to a Java Gateway before it can be used.

You use this constructor to create an extended Terminal (an extended terminal is one that allows you to have features such as signon type, read timeout and so on).


Terminal

public Terminal(JavaGateway jgate,
                java.lang.String server,
                java.lang.String devtype,
                java.lang.String netname)
         throws java.io.IOException,
                EPIException
Constructs a basic terminal to the given server using the given gateway and automatically connects the terminal.

Parameters:
jgate - the Java Gateway to use
server - the name of the server to connect to
devtype - device type that the terminal should use - can be null
netname - netname that the terminal should use - can be null
Throws:
java.io.IOException - if an error occurs connecting to the gateway
EPIException - if an error occurs creating the terminal

Terminal

public Terminal(JavaGateway jgate,
                java.lang.String server,
                java.lang.String devtype,
                java.lang.String netname,
                Terminal.EPISignOnType signoncapability,
                java.lang.String userid,
                java.lang.String password,
                int readtimeout,
                java.lang.String encoding)
         throws java.io.IOException,
                EPIException
Constructs an extended terminal to the given server using the given gateway which must be connected to explicitly before it can be used. This allows the application to do security checks before attempting to connect the terminal.

Parameters:
jgate - the Java Gateway to use
server - the name of the server to connect to
devtype - device type that the terminal should use - can be null
netname - netname that the terminal should use - can be null
signoncapability - Signon Capability EPI_SIGNON_CAPABLE or EPI_SIGNON_INCAPABLE (see setSignonCapability for more info)
userid - Userid to associate with the terminal
password - Password to associate with the terminal
readtimeout - Read Timeout (0-3600 secs, 0 = infinite) (see setReadTimeout for more info)
encoding - the java encoding for the 3270 datastream
Throws:
java.io.IOException - if an error occurs connecting to the gateway
EPIException - if an error occurs with the encoding
Method Detail

connect

public void connect(Session session,
                    int installtimeout)
             throws java.io.IOException,
                    EPIException
Connects an extended terminal to the CICS server.

This version of connect allows you to define the terminal connection timeout and whether you want to install synchronously or asynchronously by providing an appropriate session object.

Specified by:
connect in interface TerminalInterface
Parameters:
session - the Session that will handle responses from the server. If this is null, no Session is used and calls are handled synchronously.
installtimeout - Terminal Install timeout (0-3600 secs, 0 = infinite)
Throws:
java.io.IOException - if an error occurs connecting to the gateway
EPIException - if the current Java Gateway is in use.

connect

public void connect(int installtimeout)
             throws java.io.IOException,
                    EPIException
Connects an extended terminal to the CICS server.

This version of connect allows you to define the terminal connection timeout. It will use the session given to it from a setSession call or null if no session object has been supplied. Null implies synchronous.

Specified by:
connect in interface TerminalSession
Parameters:
installtimeout - Terminal Install timeout (0-3600 secs, 0 = infinite)
Throws:
java.io.IOException - if an error occurs connecting to the gateway
EPIException - if the current Java Gateway is in use.

connect

public void connect()
             throws java.io.IOException,
                    EPIException
Connects a basic or extended terminal to the server.

Specified by:
connect in interface TerminalSession
Throws:
java.io.IOException - if an error occurs connecting to the gateway
EPIException - if an error occurs creating the terminal, or the terminal is already connected.

send

public void send(Session session,
                 java.lang.String transid,
                 java.lang.String data)
          throws EPIException,
                 java.io.IOException
Starts a transaction on the server. The terminal must be in the idle state or txnTimedOut state. If a transaction has timed out it is perfectly reasonable to start another transaction, in this case it is assumed the application is aware that the previous transaction has timed out and is attempting to start another transaction, thus delivery of an exception about the transaction timeout is not required when this method is invoked.

Specified by:
send in interface TerminalInterface
Parameters:
session - the Session that will handle responses from the server. If this is null, no Session is used and calls are handled synchronously.
transid - the transaction to start
data - the data to pass to the transaction
Throws:
java.io.IOException - if an error occurs connecting to the gateway
EPIException - if the EPI call fails

send

public void send(java.lang.String transid,
                 java.lang.String data)
          throws EPIException,
                 java.io.IOException
Starts a transaction on the server using the current session. The terminal must be in the idle state or txnTimedOut state. If a transaction has timed out it is perfectly reasonable to start another transaction, in this case it is assumed the application is aware that the previous transaction has timed out and is attempting to start another transaction, thus delivery of an exception about the transaction timeout is not required when this method is invoked.

Specified by:
send in interface TerminalSession
Parameters:
transid - the transaction to start
data - the data to pass to the transaction
Throws:
java.io.IOException - if an error occurs connecting to the gateway
EPIException - if the EPI call fails

send

public void send(Session session)
          throws EPIException,
                 java.io.IOException
Sends the current screen to the server. This method is used when the terminal state is in client mode or the screen is already set up to start the next transaction, and thus the terminal is in idle state.

If the terminal is in txnTimedOut state, then this indicates the transaction has timedout, but the application has not been notified through an exception or the handleException on a Session object that this has occurred. This method will throw the exception and reset the terminal state to idle.

Specified by:
send in interface TerminalInterface
Parameters:
session - the Session that will handle responses from the server. If this is null, no Session is used and calls are handled synchronously.
Throws:
java.io.IOException - if an error occurs connecting to the gateway
EPIException - if the EPI call fails

send

public void send()
          throws EPIException,
                 java.io.IOException
Sends the current screen to the server using the current session. This method is used when the terminal state is in client state or the screen is already set up to start the next transaction and the terminal is in idle state.

If the terminal is in txnTimedOut state, then this indicates the transaction has timedout, but the application has not been notified through an exception or the handleException on a Session object that this has occurred. This method will throw the exception and reset the terminal state to idle.

Specified by:
send in interface TerminalSession
Throws:
java.io.IOException - if an error occurs connecting to the gateway
EPIException - if the EPI call fails

disconnect

public void disconnect()
                throws java.io.IOException,
                       EPIException
Disconnects the terminal from the server. The terminal state allowed are idle, client for PseudoConversions, or error.

If the purge flag has been set, then disconnect is allowed unless the terminal isn't connected.

The purge function does not cancel ATI requests queued against the terminal.

Specified by:
disconnect in interface TerminalSession
Throws:
java.io.IOException - if an error occurs connecting to the gateway
EPIException - if the EPI call fails

verifyPassword

public EPISecurityAttrs verifyPassword()
                                throws EPIGatewayException,
                                       EPISecurityException,
                                       java.io.IOException,
                                       TerminalException
Verifies the user ID and password with the External Security Manager.

Specified by:
verifyPassword in interface TerminalSession
Returns:
SecurityAttr object containing security information
Throws:
java.io.IOException - if an error occurs connecting to the gateway
EPISecurityException - if an ESI call fails
EPIGatewayException
TerminalException

changePassword

public EPISecurityAttrs changePassword(java.lang.String newPass)
                                throws EPIGatewayException,
                                       EPISecurityException,
                                       java.io.IOException,
                                       TerminalException
Allows you to change the password for a given user ID and current password with the External Security Manager.

Specified by:
changePassword in interface TerminalSession
Returns:
SecurityAttr object containing security information
Throws:
java.io.IOException - if an error occurs connecting to the gateway
EPISecurityException - if an ESI call fails
EPIGatewayException
TerminalException

queryATI

public boolean queryATI()
                 throws EPIException,
                        java.io.IOException
Returns a boolean indicating whether the terminal ATI state is enabled or disabled.

Specified by:
queryATI in interface TerminalSession
Returns:
true if ATI is enabled, false otherwise
Throws:
java.io.IOException - if an error occurs connecting to the gateway
EPIException - if the EPI call fails

setATI

public void setATI(boolean on)
            throws EPIException,
                   java.io.IOException
Sets the terminal ATI state to be enabled or disabled. ATI is not enabled unless you have associated an asynchronous Session object with the terminal.

Specified by:
setATI in interface TerminalSession
Parameters:
on - true to set ATI enabled, false otherwise
Throws:
java.io.IOException - if an error occurs connecting to the gateway
EPIException - if the EPI call fails

getServerName

public java.lang.String getServerName()
Returns the name of the server the terminal is connected to, or will be connected to if the terminal is not currently connected.

Returns:
the name of the server

getNetName

public java.lang.String getNetName()
Returns the netname of the terminal, or the netname to be used if the terminal is not currently connected.

Returns:
the netname

getDeviceType

public java.lang.String getDeviceType()
Returns the device type of the terminal, or the device type to be used if the terminal is not currently connected.

Returns:
the device type.

getSignonString

public java.lang.String getSignonString()
Gets the Signon Capability set in this object and return it as a string.

The String returned is the name of the appropriate Terminal enumeration for signon capabilities.
e.g. if the signon capability is EPI_SIGNON_CAPABLE then the string returned will be "EPI_SIGNON_CAPABLE". If the value is not valid then the string returned will be "EPI_SIGNON_INVALID"

Returns:
String The signon capability as a string
See Also:
getSignonCapability()

getUserid

public java.lang.String getUserid()
Returns the user ID associated with the terminal, or null if the user ID is null or the terminal is a basic terminal.

Specified by:
getUserid in interface TerminalSession
Returns:
the userid.

getPassword

public java.lang.String getPassword()
Returns the password associated with the terminal, or null if the password is null or the terminal is a basic terminal.

Specified by:
getPassword in interface TerminalSession
Returns:
the password.

getSignonCapability

public Terminal.EPISignOnType getSignonCapability()
If the terminal is connected, the signon capability of the associated EPI terminal is returned. If the terminal is disconnected, and the terminal is an extended terminal type, the required signon capability is returned. Use either the extended Terminal constructor or the setSignonCapability() method to set the required signon capability. If the terminal is a basic terminal type and is disconnected, this method returns EPI_SIGNON_UNKNOWN.

Returns:
signoncapability

getReadTimeout

public int getReadTimeout()
Returns the read timeout associated with this terminal or the read timeout to be set if the terminal is not connected. A basic terminal will return a readtimeout of 0.

Returns:
read timeout

getInstallTimeout

public int getInstallTimeout()
Returns the install timeout associated with this terminal. A basic terminal will return an install timeout of 0.

Returns:
install timeout

isPurgeOnDisconnect

public boolean isPurgeOnDisconnect()
Returns the purgeOnDisconnect flag for this terminal.

The purge function does not cancel ATI requests queued against the terminal.

Returns:
flag

isExtendedTerminal

public boolean isExtendedTerminal()
Returns whether the connected terminal is extended or not, or the type of terminal that will be requested if not connected.

Returns:
flag

getEncoding

public java.lang.String getEncoding()
Returns the current encoding used for a connected extended terminal or the encoding to be used if an extended terminal is not connected. A basic Terminal will always return null and use the same encoding as the Gateway daemon.

Returns:
Encoding

getTermid

public java.lang.String getTermid()
Returns the terminal ID associated with the terminal.

Specified by:
getTermid in interface TerminalSession
Returns:
the terminal ID

getScreen

public Screen getScreen()
Returns the screen associated with the terminal.

Specified by:
getScreen in interface TerminalSession
Returns:
the screen

getTransID

public java.lang.String getTransID()
Returns the transaction ID of the current transaction. This may be null if there is no transaction running or the transaction ID is not known.

If another transaction was started by the host transaction using ReturnImmediate then this method will not return the name of the transaction running, but the last transaction ID known.

Returns:
the transaction ID

getState

public int getState()
Returns the state of the terminal as defined in TerminalSession.

Specified by:
getState in interface TerminalSession
Returns:
the state
See Also:
TerminalSession

getEndReason

public int getEndReason()
Returns the end reason code.

Returns:
the end reason code

getEndReasonString

public java.lang.String getEndReasonString()
Returns the end reason code as a string.

Returns:
end reason code in form of a String

setGateway

public void setGateway(JavaGateway jgate)
                throws java.io.IOException,
                       TerminalException
Sets the Java Gateway that this terminal should use to connect to the server.

Specified by:
setGateway in interface TerminalInterface
Parameters:
jgate - a JavaGateway object
Throws:
java.io.IOException - if an error occurs connecting to the gateway
TerminalException - if the current Java Gateway is in use.

setServerName

public void setServerName(java.lang.String server)
                   throws TerminalException
Sets the name of the server the terminal should connect to. This only affects a terminal at connection time, i.e. when connect() is invoked.

Parameters:
server - the name of the server
Throws:
TerminalException - if the terminal is not in the disconnected state.

setNetName

public void setNetName(java.lang.String netname)
                throws TerminalException
Sets the netname that terminal should use. This only affects a terminal at connection time, i.e. when connect() is invoked.

Parameters:
netname - the netname
Throws:
TerminalException - if the terminal is not in the disconnected state.

setDeviceType

public void setDeviceType(java.lang.String devtype)
                   throws TerminalException
Sets the device type the terminal should use. This only affects a terminal at connection time, i.e. when connect() is invoked.

Parameters:
devtype - the device type
Throws:
TerminalException - if the terminal is not in the disconnected state.

setUserid

public void setUserid(java.lang.String newUserid)
Sets the user ID associated with the terminal. This won't be picked up until another send is done or the terminal is connected.

Invoking this method automatically flags the terminal as an extended type of terminal supporting the terminal features.

Specified by:
setUserid in interface TerminalSession
Parameters:
newUserid - the userid.

setPassword

public void setPassword(java.lang.String password)
Sets the password associated with the terminal. This won't be picked up until another send is done or the terminal is connected.

Invoking this method automatically flags the terminal as an extended type of terminal supporting the terminal features.

Specified by:
setPassword in interface TerminalSession
Parameters:
password - the password.

setSignonCapability

public void setSignonCapability(Terminal.EPISignOnType signoncapability)
                         throws TerminalException
Sets the signon capability associated with the terminal. This only affects a terminal at connection time, i.e. when connect() is invoked.

Valid entries are EPI_SIGNON_CAPABLE or EPI_SIGNON_INCAPABLE if an invalid entry is provided, EPI_SIGNON_CAPABLE is assumed.

Invoking this method automatically flags the terminal as an extended type of terminal supporting the terminal features.

Parameters:
signoncapability - the signon capability.
Throws:
TerminalException - if the terminal is not in the disconnected state.

setReadTimeout

public void setReadTimeout(int readtimeout)
                    throws TerminalException
Sets the read timeout associated with the terminal. This only affects a terminal at connection time, i.e. when connect() is invoked.

The valid range is 0-3600. Less than 0 will equate to 0, greater than 3600 will equate to 3600.

Invoking this method automatically flags the terminal as an extended type of terminal supporting the terminal features.

Parameters:
readtimeout - the read timeout.
Throws:
TerminalException - if the terminal is not in the disconnected state.

setInstallTimeout

public void setInstallTimeout(int installtimeout)
                       throws TerminalException
Sets the install timeout associated with the terminal. This only affects a terminal at connection time, i.e. when connect() is invoked. The valid range is 0-3600. Less than 0 will equate to 0, greater than 3600 will equate to 3600.

Invoking this method automatically flags the terminal as an extended type of terminal supporting the terminal features.

Parameters:
installtimeout - the install timeout.
Throws:
TerminalException - if the terminal is not in the disconnected state.

setPurgeOnDisconnect

public void setPurgeOnDisconnect(boolean flag)
Sets whether a terminal will purge on disconnect or not.

The purge function does not cancel ATI requests queued against the terminal.

Parameters:
flag - indicates whether to purge or not

setExtendedTerminal

public void setExtendedTerminal(boolean flag)
Sets whether this terminal is an extended terminal or not.

Parameters:
flag - indicates whether to make it extended or not.

setEncoding

public void setEncoding(java.lang.String newEncoding)
                 throws TerminalException,
                        java.io.UnsupportedEncodingException
Sets the Java Encoding associated with the terminal. This only affects a terminal at connection time, i.e. when connect() is invoked.

Invoking this method automatically flags the terminal as an extended type of terminal supporting the terminal features.

A encoding of null means use the default for 3270 data streams.

Parameters:
newEncoding - the Java Encoding to use
Throws:
TerminalException - if the terminal is not in the disconnected state.
java.io.UnSupportedEncodingException
java.io.UnsupportedEncodingException

setSession

public void setSession(Session newSess)
Set the Session object associated with the terminal.

Specified by:
setSession in interface TerminalInterface
Parameters:
newSess - a Session object

©Copyright IBM Corp. 1994, 2014
Legal