com.ibm.ctg.epi

Class Terminal

  • java.lang.Object
    • com.ibm.ctg.epi.Terminal
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class and Description
      static class  Terminal.EPISignOnType
      Class to allow for compile time checking of signon enumerations.
    • Constructor Summary

      Constructors 
      Constructor and Description
      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

      Methods 
      Modifier and Type Method and Description
      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 = no timeout)
        Throws:
        java.io.IOException - if an error occurs connecting to the gateway
        EPIException - if an error occurs creating the terminal, the terminal is already connected, or if the connect is attempted on a non-extended terminal
        See Also:
        EPIException.getErrorCode()
      • 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 = no timeout)
        Throws:
        java.io.IOException - if an error occurs connecting to the gateway
        EPIException - if an error occurs creating the terminal, the terminal is already connected, or if the connect is attempted on a non-extended terminal
        See Also:
        EPIException.getErrorCode()
      • 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.
        See Also:
        EPIException.getErrorCode()
      • 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 timed out, 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 timed out, 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 states 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
      • 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 will not 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 will not 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.

        An 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, 2013
Legal