com.ibm.ctg.client

Class EPIRequest

  • All Implemented Interfaces:
    EPIEndReasonCodes, EPIReturnCodes, GatewayReturnCodes


    public class EPIRequest
    extends GatewayRequest
    implements EPIReturnCodes, EPIEndReasonCodes
    This class contains the details of an EPI request to the CICS Transaction Gateway. To run the request, the EPIRequest object should be flowed to the Gateway using the JavaGateway.flow method. NOTE: It is not allowed to manually to stop the EPI environment, since this is done when the Gateway itself terminates.

    For examples of using this class please refer to the supplied EPI samples.

    See Also:
    GatewayRequest
    • Field Detail

      • EPI_INITIALIZE

        public static final int EPI_INITIALIZE
        Initialize the EPI. This is done by the Gateway daemon.
        See Also:
        Constant Field Values
      • EPI_LIST_SYSTEMS

        public static final int EPI_LIST_SYSTEMS
        List of CICS servers.
        See Also:
        Constant Field Values
      • EPI_ADD_TERMINAL

        public static final int EPI_ADD_TERMINAL
        Install a terminal resource.
        See Also:
        Constant Field Values
      • EPI_INQUIRE_SYSTEM

        public static final int EPI_INQUIRE_SYSTEM
        Inquire as to server on which terminal exists.
        See Also:
        Constant Field Values
      • EPI_DEL_TERMINAL

        public static final int EPI_DEL_TERMINAL
        Delete a terminal resource.
        See Also:
        Constant Field Values
      • EPI_START_TRAN

        public static final int EPI_START_TRAN
        Start a transaction.
        See Also:
        Constant Field Values
      • EPI_REPLY

        public static final int EPI_REPLY
        Send a reply (used after an EPI_EVENT_CONVERSE has been received).
        See Also:
        Constant Field Values
      • EPI_ATI_STATE

        public static final int EPI_ATI_STATE
        Change or get the ATI state of a terminal resource.
        See Also:
        Constant Field Values
      • EPI_GET_EVENT

        public static final int EPI_GET_EVENT
        Get event information.
        See Also:
        Constant Field Values
      • EPI_PURGE_TERMINAL

        public static final int EPI_PURGE_TERMINAL
        Purge a terminal resource.
        See Also:
        Constant Field Values
      • EPI_ADD_EX_TERMINAL

        public static final int EPI_ADD_EX_TERMINAL
        Install an extended terminal resource.
        See Also:
        Constant Field Values
      • EPI_SET_SECURITY

        public static final int EPI_SET_SECURITY
        Change the security for an installed terminal.
        See Also:
        Constant Field Values
      • EPI_SYSTEM_MAX

        public static final int EPI_SYSTEM_MAX
        Maximum length of CICS server name.
        See Also:
        Constant Field Values
      • EPI_DESCRIPTION_MAX

        public static final int EPI_DESCRIPTION_MAX
        Maximum length of CICS server description.
        See Also:
        Constant Field Values
      • EPI_NETNAME_MAX

        public static final int EPI_NETNAME_MAX
        Maximum length of terminal's netName.
        See Also:
        Constant Field Values
      • EPI_TRANSID_MAX

        public static final int EPI_TRANSID_MAX
        Maximum length of CICS server transaction ID.
        See Also:
        Constant Field Values
      • EPI_ABEND_MAX

        public static final int EPI_ABEND_MAX
        Maximum length of CICS abend code.
        See Also:
        Constant Field Values
      • EPI_DEVTYPE_MAX

        public static final int EPI_DEVTYPE_MAX
        Maximum length of model terminal definition.
        See Also:
        Constant Field Values
      • EPI_ERROR_MAX

        public static final int EPI_ERROR_MAX
        Maximum length of error text.
        See Also:
        Constant Field Values
      • EPI_USERID_MAX

        public static final int EPI_USERID_MAX
        Maximum length of user ID.
        See Also:
        Constant Field Values
      • EPI_PASSWORD_MAX

        public static final int EPI_PASSWORD_MAX
        Maximum length of password.
        See Also:
        Constant Field Values
      • EPI_MAPNAME_MAX

        public static final int EPI_MAPNAME_MAX
        Maximum length of map name.
        See Also:
        Constant Field Values
      • EPI_MAPSETNAME_MAX

        public static final int EPI_MAPSETNAME_MAX
        Maximum length of map set name.
        See Also:
        Constant Field Values
      • EPI_TERMID_MAX

        public static final int EPI_TERMID_MAX
        Maximum length of terminal ID.
        See Also:
        Constant Field Values
      • EPI_TERM_INDEX_NONE

        public static final int EPI_TERM_INDEX_NONE
        termIndex not specified. This is an INVALID value.
        See Also:
        Constant Field Values
      • EPI_MIN_TERMINDEX

        public static final int EPI_MIN_TERMINDEX
        Minimum termIndex value.
        See Also:
        Constant Field Values
      • EPI_ERRLASTLINE

        public static final int EPI_ERRLASTLINE
        Terminal displays error messages on last row.
        See Also:
        Constant Field Values
      • EPI_ERRINTENSIFY

        public static final int EPI_ERRINTENSIFY
        Terminal displays error messages intensified.
        See Also:
        Constant Field Values
      • EPI_HILIGHT

        public static final int EPI_HILIGHT
        Terminal resource supports extended highlighting.
        See Also:
        Constant Field Values
      • EPI_COLOR

        public static final int EPI_COLOR
        Terminal resource supports color.
        See Also:
        Constant Field Values
      • EPI_NOEVENT

        public static final int EPI_NOEVENT
        No events returned for this terminal resource.
        See Also:
        Constant Field Values
      • EPI_EVENT_SEND

        public static final int EPI_EVENT_SEND
        A transaction has sent 3270 data to a terminal resource (no reply is expected).
        See Also:
        Constant Field Values
      • EPI_EVENT_CONVERSE

        public static final int EPI_EVENT_CONVERSE
        A transaction is expecting an EPI_REPLY.
        See Also:
        Constant Field Values
      • EPI_EVENT_END_TRAN

        public static final int EPI_EVENT_END_TRAN
        A transaction has ended. If it was pseudoconversational then Transid contains the next transaction.
        See Also:
        Constant Field Values
      • EPI_EVENT_START_ATI

        public static final int EPI_EVENT_START_ATI
        An ATI transaction has been started against the terminal.
        See Also:
        Constant Field Values
      • EPI_EVENT_END_TERM

        public static final int EPI_EVENT_END_TERM
        This terminal resource no longer exists - check endReason value.
        See Also:
        Constant Field Values
      • EPI_EVENT_ADD_TERM

        public static final int EPI_EVENT_ADD_TERM
        An Add Terminal event has been received.
        See Also:
        Constant Field Values
      • EPI_ATI_ON

        public static final int EPI_ATI_ON
        Allow ATI requests and return the previous ATI state.
        See Also:
        Constant Field Values
      • EPI_ATI_HOLD

        public static final int EPI_ATI_HOLD
        Hold ATI requests and return the previous ATI state.
        See Also:
        Constant Field Values
      • EPI_ATI_QUERY

        public static final int EPI_ATI_QUERY
        Return the current ATI state.
        See Also:
        Constant Field Values
      • EPI_WAIT

        public static final int EPI_WAIT
        Wait for the next terminal event to occur.
        See Also:
        Constant Field Values
      • EPI_NOWAIT

        public static final int EPI_NOWAIT
        Return immediately (with Cics_Rc). Not currently recommended.
        See Also:
        Constant Field Values
      • EPI_ADD_SYNC

        public static final int EPI_ADD_SYNC
        Add terminal synchronously.
        See Also:
        Constant Field Values
      • EPI_ADD_ASYNC

        public static final int EPI_ADD_ASYNC
        Add terminal asynchronously.
        See Also:
        Constant Field Values
      • EPI_SIGNON_CAPABLE

        public static final int EPI_SIGNON_CAPABLE
        Signon capable terminal.
        See Also:
        Constant Field Values
      • EPI_SIGNON_INCAPABLE

        public static final int EPI_SIGNON_INCAPABLE
        Signon incapable terminal.
        See Also:
        Constant Field Values
      • EPI_SIGNON_UNKNOWN

        public static final int EPI_SIGNON_UNKNOWN
        Signon capability unknown.
        See Also:
        Constant Field Values
      • Call_Type

        public int Call_Type
        Type of EPI call.

        EPI_INITIALIZE, EPI_LIST_SYSTEMS, EPI_ADD_TERMINAL, EPI_INQUIRE_SYSTEM, EPI_DEL_TERMINAL, EPI_START_TRAN, EPI_REPLY, EPI_ATI_STATE, EPI_GET_EVENT, EPI_PURGE_TERMINAL, EPI_ADD_EX_TERMINAL, EPI_SET_SECURITY.

      • Server

        public java.lang.String Server
        CICS server to use (or which are using). If this is left unset, the default server defined in the gateway is used.
      • Cics_Rc

        public int Cics_Rc
        CICS return code.
      • deviceType

        public java.lang.String deviceType
        CICS model terminal name - defined in CICS server environment.
      • signonCapability

        public int signonCapability
        Signon capability of the terminal. Indicates whether the application may start server-provided signon and signoff transactions from the terminal resource.
      • addtype

        public int addtype
        Method of adding a terminal either synchronously (EPI_ADD_SYNC) or asynchronously (EPI_ADD_ASYNC).
      • installTimeout

        public int installTimeout
        Terminal Install Timeout. The maximum time in seconds that the installation of a terminal resource may take.
      • readTimeout

        public int readTimeout
        Terminal Read Timeout. The maximum amount of time in seconds permitted between notification of a CICS_EPI_EVENT_CONVERSE event for the terminal resource and the following invocation of the CICS_EpiReply.
      • CCSid

        public int CCSid
        Terminal Code Page. The coded character set identifier used to identify the coded graphic character set used by the application for data passed between the terminal resource and CICS transactions.
      • userid

        public java.lang.String userid
        User ID associated with the terminal.
      • password

        public java.lang.String password
        Password associated with the terminal.
      • atiState

        public int atiState
        Input and output field for atiState() calls (Call_Type = EPI_ATI_STATE)
      • waitState

        public int waitState
        Input for getEvent() calls (Call_Type = EPI_GET_EVENT).
      • netName

        public java.lang.String netName
        Netname - platform dependent.
      • numLines

        public int numLines
        Number of rows supported by the terminal resource.
      • numColumns

        public int numColumns
        Number of columns supported by the terminal resource.
      • maxData

        public int maxData
        The maximum amount of data that could be sent to this terminal resource, and it also represents the maximum amount of data that should be sent by this terminal resource. This is a read only value set when a terminal is added successfully. Maximum size may be defined in the model terminal definition on the CICS server. If it is not specified, a default value of 12000 is assumed.
      • errLastLine

        public int errLastLine
        1 = error messages displayed on last row; else 0.
      • errIntensify

        public int errIntensify
        1 = error messages displayed intensified, else 0.
      • errColor

        public int errColor
        3270 color attribute used for error messages.
      • errHilight

        public int errHilight
        3270 highlight attribute used for error messages.
      • hilight

        public int hilight
        1 = terminal resource supports extended highlighting; else 0.
      • color

        public int color
        1 = terminal resource supports color; else 0.
      • termID

        public java.lang.String termID
        The name of the terminal resource.
      • termIndex

        public int termIndex
        The terminal index identifying the terminal resource.
      • event

        public int event
        Type of event that has completed.
      • endReason

        public int endReason
        Reason why the terminal resource was deleted.
      • Transid

        public java.lang.String Transid
        Transaction to be run on the CICS server.
      • data

        public byte[] data
        CICS 3270 data stream in byte array
      • size

        public int size
        Total length of the 3270 datastream from the CICS server. If the byte array provided to hold the data stream if smaller than this value, then the 3270 stream will be truncated.
      • mapName

        public java.lang.String mapName
        The map name for the transaction (if any).
      • mapSetName

        public java.lang.String mapSetName
        The map set name for the transaction (if any).
      • endReturnCode

        public int endReturnCode
        The return code for END_TRAN and ADD_TERM events.
      • SystemList

        public java.util.Vector SystemList
        Vector of CICS servers and their descriptions: 1st element is server, 2nd element is description, etc.
      • maxNumServers

        public int maxNumServers
        Maximum number of CICS servers about which info is to be returned (input to listSystems()).
      • numServersKnown

        public int numServersKnown
        Number of CICS servers which are defined (output from listSystems() flow).
      • numServersReturned

        public int numServersReturned
        Number of CICS servers about which information has been returned (output from listSystems() flow).
    • Constructor Detail

      • EPIRequest

        public EPIRequest()
        Creates an EPIRequest object with default values. Defaults: addtype = EPI_ADD_SYNC, server = null, Transid = null, signonCapability = EPI_SIGNON_UNKNOWN, installTimeout = 0, readTimeout = 0, userid = null, password = null, waitState = EPI_NOWAIT, Call_Type = 0.

        As all the valid EPIRequest parameters are public they may be set directly.

      • EPIRequest

        public EPIRequest(int iCallType)
        Creates an EPIRequest object with default values, but setting Call_Type value.
        Parameters:
        iCallType - Call Type
      • EPIRequest

        public EPIRequest(int iCallType,
                  int itermIndex)
        Creates an EPIRequest object with default values, but setting Call_Type and termIndex values.

        This constructor will create an object that is suitable for EPI_INQUIRE_SYSTEM, EPI_DEL_TERMINAL and EPI_GET_SYS_ERROR.

        Parameters:
        iCallType - Call Type
        itermIndex - Terminal Index
    • Method Detail

      • listSystems

        public static EPIRequest listSystems(int iNumOfSys)
        This method returns a new EPIRequest object which can be used to effect a CICS_EpiListSystems on the CICS Transaction Gateway. The returned object should be flowed to the Gateway as is.

        Upon return for the flow call, the public data Vector EPIRequest.SystemsList will contain the returned system names and descriptions.

        Upon return from the flow call, numServersKnown and numServersReturned will also have been updated.

        There is no guarantee that a communications link exists between the CICS Transaction Gateway and any server in the list, or that any of the CICS servers are available.

        Parameters:
        iNumOfSys - Maximum number of systems to request information on
      • addTerminal

        public static EPIRequest addTerminal(java.lang.String strServer,
                             java.lang.String strNetName,
                             java.lang.String strDeviceType)
        This method returns a new EPIRequest object which can be used to effect a CICS_EpiAddTerminal on the CICS Transaction Gateway. The returned object should be flowed to the Gateway as is.

        This method installs a new terminal resource, or reserves an existing one. It returns a termIndex which should be used to identify the terminal resource on other EPI calls.

        If strServer is not supplied then, currently, the default server is selected. The default server is defined as the first server listed within the ini file.

        If a strNetName is not supplied then one is returned in netName. If a strNetName is supplied but it does not match an existing terminal resource in the server, then the server installs a terminal resource using the strDeviceType and gives it the strNetName. (In this case if strDeviceType is null then an error is returned.)

        If a strDeviceType is not supplied and a new terminal resource is installed, then the selected terminal type is not predictable. A strDeviceType is recommended (the value of this will depend on your server setup).

        After a terminal resource has been added, the default ATIState is EPI_ATI_HOLD i.e. ATI requests will be NOT be processed. EPIRequests to start a transaction (startTran method) are NOT ATI requests, but terminal requests. To enable ATI requests to be processed the atiState should be changed to EPI_ATI_ON. This can be done by setting the iATIState to EPI_ATI_ON using the atiState method.

        NOTE: Callback routines are specified NOT on the addTerminal request, but on the getEvent request (using the getEventWithCallback method).

        Parameters:
        strServer - CICS server name to make request to
        strNetName - CICS terminal resource name
        strDeviceType - CICS terminal model name
      • addTerminal

        public static EPIRequest addTerminal(java.lang.String strServer,
                             java.lang.String strNetName,
                             java.lang.String strDeviceType,
                             java.lang.String strUserid,
                             java.lang.String strPassword,
                             int iInstallTimeout,
                             int iReadTimeout,
                             int iSignonCapability,
                             int iCCSid)
        This method returns a new EPIRequest object which can be used to effect a CICS_EpiAddExTerminal on the CICS Transaction Gateway. The returned object should be flowed to the Gateway as is.

        This method installs a new terminal resource, or reserves an existing one. It returns a termIndex which should be used to identify the terminal resource on other EPI calls.

        If strServer is not supplied then, currently, the default server is selected. The default server is defined as the first server listed within the ini file.

        If a strNetName is not supplied then one is returned in netName. If a strNetName is supplied but it does not match an existing terminal resource in the server, then the server installs a terminal resource using the strDeviceType and gives it the strNetName. (In this case if strDeviceType is null then an error is returned.)

        If a strDeviceType is not supplied and a new terminal resource is installed, then the selected terminal type is not predictable. Provision of a strDeviceType is recommended (the value of this will depend on your server setup).

        After a terminal resource has been added, the default ATIState is EPI_ATI_HOLD i.e. ATI requests will be NOT be processed. EPIRequests to start a transaction (startTran method) are NOT ATI requests, but terminal requests. To enable ATI requests to be processed the atiState should be changed to EPI_ATI_ON. This can be done by setting the iATIState to EPI_ATI_ON using the atiState method.

        NULL is allowed for userid or password, and is treated the same as an empty string. If the CICS server rejects the install request due to an incorrect user ID or password, the response code will be EPI_ERR_SECURITY.

        NOTE: Callback routines are specified NOT on the addTerminal request, but on the getEvent request (using the getEventWithCallback method).

        Parameters:
        strServer - CICS server name to make request to
        strNetName - CICS terminal resource name
        strDeviceType - CICS terminal model name
        strUserid - Userid to associate with the terminal
        strPassword - Password to associate with the terminal
        iInstallTimeout - Terminal Install timeout (0-3600 secs, 0 = infinite)
        iReadTimeout - Read Timeout (0-3600 secs, 0 = infinite)
        iSignonCapability - Signon Capability EPI_SIGNON_CAPABLE or EPI_SIGNON_INCAPABLE
      • addTerminalAsync

        public static EPIRequest addTerminalAsync(java.lang.String strServer,
                                  java.lang.String strNetName,
                                  java.lang.String strDeviceType,
                                  java.lang.String strUserid,
                                  java.lang.String strPassword,
                                  int iInstallTimeout,
                                  int iReadTimeout,
                                  int iSignonCapability,
                                  int iCCSid)
        This method returns a new EPIRequest object which can be used to effect a CICS_EpiAddExTerminal on the CICS Transaction Gateway. The returned object should be flowed to the Gateway as is.

        When flowed the calling application thread will resume once the request to install the terminal resource has been accepted as opposed to completed with other addTerminal methods. At the point of thread resumption the parameters have been validated. Assuming the parameters are valid, the terminal resource is installed and a CICS_EPI_EVENT_ADD_TERM event is generated. The terminal index will then be available for retrieval by the application thread with a subsequent getEvent or if using callbacks will be returned to the setResults routine. This is in contrast to other addTerminal requests which allow the application thread to resume only once the terminal resource has been installed. In this case the returned information is immediately available.

        If strServer is not supplied then, currently, the default server is selected. The default server is defined as the first server listed within the ini file.

        If a strNetName is not supplied then one is returned in netName. If a strNetName is supplied but it does not match an existing terminal resource in the server, then the server installs a terminal resource using the strDeviceType and gives it the strNetName. (In this case if strDeviceType is null then an error is returned.)

        If a strDeviceType is not supplied and a new terminal resource is installed, then the selected terminal type is not predictable. Provision of a strDeviceType is recommended (the value of this will depend on your server setup).

        NULL is allowed for userid or password, and is treated the same as an empty string. If the CICS server rejects the install request due to an incorrect user ID or password, the response code will be EPI_ERR_SECURITY.

        After a terminal resource has been added, the default ATIState is EPI_ATI_HOLD i.e. ATI requests will be NOT be processed. EPIRequests to start a transaction (startTran method) are NOT ATI requests, but terminal requests. To enable ATI requests to be processed the atiState should be changed to EPI_ATI_ON. This can be done by setting the iATIState to EPI_ATI_ON using the atiState method.

        NOTE: Callback routines are specified NOT on the addTerminal request, but on the getEvent request (using the getEventWithCallback method).

        Parameters:
        strServer - CICS server name to make request to
        strNetName - CICS terminal resource name
        strDeviceType - CICS terminal model name
        strUserid - Userid to associate with the terminal
        strPassword - Password to associate with the terminal
        iInstallTimeout - Terminal Install timeout (0-3600 secs, 0 = infinite)
        iReadTimeout - Read Timeout (0-3600 secs, 0 = infinite)
        iSignonCapability - Signon Capability EPI_SIGNON_CAPABLE or EPI_SIGNON_INCAPABLE
        iCCSid - code page
      • getCallType

        public int getCallType()
        Returns the Call_Type set in this object.
        Returns:
        int The Call_Type
      • getCallTypeString

        public java.lang.String getCallTypeString()
        Returns the Call_Type set in this object, as a String.

        The String returned is the name of the appropriate Java constant e.g. if the Call_Type is EPI_ADD_TERMINAL, then the String returned will be "EPI_ADD_TERMINAL". If the Call_Type is invalid then the String returned will be "EPI_UNKNOWN_CALL_TYPE".

        Returns:
        String The Call_Type as a String
      • getRc

        public int getRc()
        Gets the return code set in this object. If a Gateway error code is set this is returned. However if there is no Gateway error code, then any CICS return code is returned. If this method returns zero, it can be assumed that no errors have occurred.

        Returns:
        int The return code
      • getRcString

        public java.lang.String getRcString()
        Gets the return code set in this object and return it as a string. If a Gateway error code is set the string equivalent is returned. However if there is no Gateway error code, then any CICS return code string is returned. If there is no error then the string EPI_NORMAL will be returned.
        Returns:
        String The return code
      • getCicsRc

        public int getCicsRc()
        Gets the CICS return code set in this object, if there is one.

        Returns:
        int The return code
      • getCicsRcString

        public java.lang.String getCicsRcString()
        Gets the CICS return code set in this object and returns it as a String.

        The String returned is the name of the appropriate Java constant e.g. if the Cics_Rc is EPI_NORMAL, then the String returned will be "EPI_NORMAL". If the Cics_Rc is unknown then the String returned will be "EPI_UNKNOWN_CICS_RC".

        Returns:
        The return code as a String
      • getEndReturnCode

        public int getEndReturnCode()
        Gets the extra CICS return code from an END_TRAN or ADD_TERM event.

        Returns:
        int The return code
      • getEndReturnCodeString

        public java.lang.String getEndReturnCodeString()
        Gets the extra CICS return code from an END_TRAN or ADD_TERM event and returns it as a String.

        The String returned is the name of the appropriate Java constant e.g. if the Cics_Rc is EPI_NORMAL, then the String returned will be "EPI_NORMAL". If the Cics_Rc is unknown then the String returned will be "EPI_UNKNOWN_CICS_RC".

        Returns:
        The return code as a String
      • getEndReason

        public int getEndReason()
        Returns the End Reason value which is set when an END_TERM event has been received.

        Returns:
        int The End Reason.
      • getEndReasonString

        public java.lang.String getEndReasonString()
        Returns the End Reason value as a string, which is set when an END_TERM event has been received.

        The String returned is the name of the appropriate Java constant e.g. if the value is EPI_END_SIGNOFF then the String returned will be "EPI_END_SIGNOFF". If the End Reason value is unknown then the String returned will be "EPI_UNKNOWN_END_REASON".

        Returns:
        The end reason as a String
      • getEvent

        public int getEvent()
        Returns the event set in this object.

        Returns:
        int The event
      • getEventString

        public java.lang.String getEventString()
        Gets the event set in this object and returns it as a String.

        The String returned is the name of the appropriate Java constant e.g. if the event is EPI_EVENT_SEND, then the String returned will be "EPI_EVENT_SEND". If the event is unknown then the String returned will be "EPI_NOEVENT".

        Returns:
        String The event as a String
      • 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 Java constant 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
      • getAddTypeString

        public java.lang.String getAddTypeString()
        Gets the add type for an extended Terminal Request for this object and returns it as a string

        The String returned is the name of the appropriate Java constant e.g. if the add type is EPI_ADD_SYNC, then the String returned will be "EPI_ADD_SYNC". If the type is unknown then the String returned will be "EPI_UNKNOWN_ADD_TYPE"

        Returns:
        String The add type as a string
      • setCallback

        public void setCallback(Callbackable callBack)
        Sets the Callbackable object associated with this object.

        If null is passed to this method then it is assumed that no Callbackable object is required.

        Parameters:
        callBack - EPI Callbackable object.
      • isCallback

        public boolean isCallback()
        This method returns a boolean indicating whether there is a Callbackable object associated with this EPIRequest object.
        Returns:
        boolean indicating whether there is a Callbackable object
      • inquireSystem

        public void inquireSystem()
        Sets the Call_Type of this object to EPI_INQUIRE_STATE.

        An EPI_INQUIRE_SYSTEM request takes a termIndex value and returns the Server on which the terminal resource (identified by the termIndex) is installed.

        Upon return for the flow call, the EPIRequest object's Server value is updated.

      • inquireSystem

        public void inquireSystem(int itermIndex)
        Sets the Call_Type of this object to EPI_INQUIRE_STATE and also sets the termIndex associated with this object.

        An EPI_INQUIRE_SYSTEM request takes a termIndex value and returns the Server on which the terminal resource (identified by the termIndex) is installed.

        Upon return for the flow call, the EPIRequest object's Server value is updated.

        Parameters:
        itermIndex - Index of terminal whose Server is to be determined
      • atiState

        public void atiState(int iATIState)
        Sets the Call_Type of this object to EPI_ATI_STATE and also sets the atiState associated with this object.

        This method allows the application to query and alter the way ATI requests are handled.

        EPI_ATI_ON enables ATI requests and, also, returns the previous ATI in variable atiState.

        EPI_ATI_HOLD enables ATI requests to be held and, also, returns the previous ATI state in the variable atiState.

        EPI_ATI_QUERY returns the current ATI state.

        Parameters:
        iATIState - ATI state
      • atiState

        public void atiState(int itermIndex,
                    int iATIState)
        Sets the Call_Type of this object to EPI_ATI_STATE and also sets the termIndex and atiState associated with this object.

        This method allows the application to query and alter the way ATI requests are handled.

        EPI_ATI_ON enables ATI requests and, also, returns the previous ATI in variable atiState.

        EPI_ATI_HOLD enables ATI requests to be held and, also, returns the previous ATI state in the variable atiState.

        EPI_ATI_QUERY returns the current ATI state.

        Parameters:
        itermIndex - Terminal Index of terminal whose atiState is to be queried or set
        iATIState - ATI state
      • startTran

        public void startTran(java.lang.String strTransid,
                     byte[] abytdata,
                     int isize)
        Sets the Call_Type of this object to EPI_START_TRAN and also sets the Transid, data and size associated with this object.

        This method allows the application to start a new transaction from a terminal resource, or continue a pseudoconversational transaction.

        Start a new transaction after EPI_ADD_TERMINAL has flowed. Or after EPI_GET_EVENT returns an event of EPI_EVENT_END_TRAN.

        Continue a pseudoconversation after EPI_GET_EVENT returns an event of EPI_EVENT_END_TRAN and the Transid returned was NOT null. In this case, if the strTransid is not null, it must be the same as the Transid returned in the preceding EPI_EVENT_END_TRAN.

        Parameters:
        strTransid - Transid to be run, or null
        abytdata - Byte array of 3270 data stream. CANNOT be null.
        isize - size, in bytes, of data stream to be passed to transaction
      • startTran

        public void startTran(int itermIndex,
                     java.lang.String strTransid,
                     byte[] abytdata,
                     int isize)
        Sets the Call_Type of this object to EPI_START_TRAN and also sets the termIndex, Transid, data and size associated with this object.

        This method allows the application to start a new transaction from a terminal resource, or continue a pseudoconversational transaction.

        Start a new transaction after EPI_ADD_TERMINAL has flowed. Or after EPI_GET_EVENT returns an event of EPI_EVENT_END_TRAN.

        Continue a pseudoconversation after EPI_GET_EVENT returns an event of EPI_EVENT_END_TRAN and the Transid returned was NOT null. In this case, if the strTransid is not null, it must be the same as the Transid returned in the preceding EPI_EVENT_END_TRAN.

        Parameters:
        itermIndex - Terminal Index of terminal that is to run transaction
        strTransid - Transid to be run, or null
        abytdata - Byte array of 3270 data stream. CANNOT be null.
        isize - size, in bytes, of data stream to be passed to transaction
      • sendReply

        public void sendReply(byte[] abytdata,
                     int isize)
        Sets the Call_Type of this object to EPI_REPLY and also sets the data and size associated with this object.

        This method allows the application to send a reply in response to a EPI_EVENT_CONVERSE.

        Parameters:
        abytdata - Byte array of 3270 data stream. CANNOT be null.
        isize - size, in bytes, of data stream to be passed to transaction
      • sendReply

        public void sendReply(int itermIndex,
                     byte[] abytdata,
                     int isize)
        Sets the Call_Type of this object to EPI_REPLY and also sets the termIndex, data and size associated with this object.

        This method allows the application to send a reply in response to a EPI_EVENT_CONVERSE.

        Parameters:
        itermIndex - Terminal Index of terminal that is to run transaction
        abytdata - Byte array of 3270 data stream. CANNOT be null.
        isize - size, in bytes, of data stream to be passed to transaction
      • getEvent

        public void getEvent(int iwaitState,
                    int isize)
        Sets the Call_Type of this object to EPI_GET_EVENT and also sets the waitState and size associated with this object.

        This method allows the application to obtain information about an event that has occurred for a terminal resource.

        If the event is EPI_EVENT_SEND then data and size are returned to the application.

        If the event is EPI_EVENT_CONVERSE then data and size are returned. The application should then issue an EPI_REPLY.

        If the event is EPI_EVENT_END_TRAN then Transid is returned if the previous transaction was pseudoconversational.

        If the event is EPI_EVENT_START_ATI then Transid is returned.

        If the event is EPI_EVENT_END_TERM then endReason is returned.

        If the event is EPI_EVENT_ADD_TERM then the variables' detail properties will be updated. Ensure size is large enough for the event data.

        NOTE: A termIndex value must be supplied before flowing the the request.

        NOTE: Ensure that the size of the data array to be returned is sufficient to hold ALL the data that may be returned. If the data is truncated (EPI_ERR_MORE_DATA) then an application/applet may not receive the end of transaction indicator (EPI_EVENT_END_TRAN).

        NOTE: We strongly recommend the use of getEvent() with iwaitState = EPI_WAIT or getEventWithCallback; NOT getEvent() with iwaitState = EPI_NOWAIT.

        NOTE: After the getEvent has completed successfully the 'size' field contains the amount of data returned by CICS. The size of the 'data' array is the input 'size' value, not the output 'size' value.

        Parameters:
        iwaitState - What should happen if no event has been generated
        isize - MAXIMUM size, in bytes, of the data to be returned
      • getEvent

        public void getEvent(int itermIndex,
                    int iwaitState,
                    int isize)
        Sets the Call_Type of this object to EPI_GET_EVENT and also sets the termIndex, waitState and size associated with this object.

        This method allows the application to obtain information about an event that has occurred for a terminal resource.

        If the event is EPI_EVENT_SEND then data and size are returned.

        If the event is EPI_EVENT_CONVERSE then data and size are returned. The application should then issue an EPI_REPLY.

        If the event is EPI_EVENT_END_TRAN then Transid is returned if the previous transaction was pseudoconversational.

        If the event is EPI_EVENT_START_ATI then Transid is returned.

        If the event is EPI_EVENT_END_TERM then endReason is returned.

        If the event is EPI_EVENT_ADD_TERM then the variables detail properties will be updated. Ensure a large enough size for the event data.

        NOTE: A termIndex value must be supplied before flowing the the request.

        NOTE: Ensure that the size of the data array to be returned is sufficient to hold ALL the data that may be returned. If the data is truncated (EPI_ERR_MORE_DATA) then an application/applet may not receive the end of transaction indicator (EPI_EVENT_END_TRAN).

        NOTE: We strongly recommend the use of getEvent() with iwaitState = EPI_WAIT or getEventWithCallback; NOT getEvent() with iwaitState = EPI_NOWAIT.

        NOTE: After the getEvent has completed successfully the 'size' field contains the amount of data returned by CICS. The size of the 'data' array is the input 'size' value, not the output 'size' value.

        Parameters:
        itermIndex - Terminal Index of terminal for which to obtain event
        iwaitState - What should happen if no event has been generated
        isize - MAXIMUM size, in bytes, of the data to be returned
      • getEventWithCallback

        public void getEventWithCallback(int isize,
                                Callbackable callBack)
        Sets the Call_Type of this object to EPI_GET_EVENT and also sets the size and Callbackable object associated with this object.

        This method allows the application to obtain information about an event that has occurred for a terminal resource. The Callbackable object is invoked when an event occurs for the specified terminal resource.

        The Callbackable object remains associated with the EPIRequest after it has been invoked, and continues to be invoked for subsequent flows unless explicitly unset by the application. To disassociate the Callbackable object from the EPIRequest and stop it being invoked for subsequent flows, applications must unset the Callbackable object after it has been invoked by calling setCallback with the callBack parameter set to null.

        If the event is EPI_EVENT_SEND then data and size are returned.

        If the event is EPI_EVENT_CONVERSE then data and size are returned. The application should then issue an EPI_REPLY.

        If the event is EPI_EVENT_END_TRAN then Transid is returned if the previous transaction was pseudoconversational.

        If the event is EPI_EVENT_START_ATI then Transid is returned.

        If the event is EPI_EVENT_END_TERM then endReason is returned.

        If the event is EPI_EVENT_ADD_TERM then the variables detail properties will be updated. Ensure a large enough size for the event data.

        NOTE: A termIndex value must be supplied before flowing the the request.

        NOTE: Ensure that the size of the data array to be returned is sufficient to hold ALL the data that may be returned. If the data is truncated (EPI_ERR_MORE_DATA) then an application/applet may not receive the end of transaction indicator (EPI_EVENT_END_TRAN).

        NOTE: After the getEvent has completed successfully the 'size' field contains the amount of data returned by CICS. The size of the 'data' array is the input 'size' value, not the output 'size' value.

        NOTE: If no Callbackable object is supplied a getEvent with EPI_WAIT will default.

        Parameters:
        isize - MAXIMUM size, in bytes, of the data to be returned
        callBack - EPI Callbackable object
      • getEventWithCallback

        public void getEventWithCallback(int itermIndex,
                                int isize,
                                Callbackable callBack)
        Sets the Call_Type of this object to EPI_GET_EVENT and also sets the termIndex, size and Callbackable object associated with this object.

        This method allows the application to obtain information about an event that has occurred for a terminal resource. The Callbackable object is invoked when an event occurs for the specified terminal resource.

        The Callbackable object remains associated with the EPIRequest after it has been invoked, and continues to be invoked for subsequent flows unless explicitly unset by the application. To disassociate the Callbackable object from the EPIRequest and stop it being invoked for subsequent flows, applications must unset the Callbackable object after it has been invoked by calling setCallback with the callBack parameter set to null.

        If the event is EPI_EVENT_SEND then data and size are returned.

        If the event is EPI_EVENT_CONVERSE then data and size are returned. The application should then issue an EPI_REPLY.

        If the event is EPI_EVENT_END_TRAN then Transid is returned if the previous transaction was pseudoconversational.

        If the event is EPI_EVENT_START_ATI then Transid is returned.

        If the event is EPI_EVENT_END_TERM then endReason is returned.

        If the event is EPI_EVENT_ADD_TERM then the variables detail properties will be updated. Ensure a large enough size for the event data.

        NOTE: A termIndex value must be supplied before flowing the the request.

        NOTE: Ensure that the size of the data array to be returned is sufficient to hold ALL the data that may be returned. If the data is truncated (EPI_ERR_MORE_DATA) then an application/applet may not receive the end of transaction indicator (EPI_EVENT_END_TRAN).

        NOTE: After the getEvent has completed successfully the 'size' field contains the amount of data returned by CICS. The size of the 'data' array is the input 'size' value, not the output 'size' value.

        NOTE: If no Callbackable object is supplied a getEvent with EPI_WAIT will default.

        Parameters:
        itermIndex - Terminal Index of terminal for which to obtain event
        isize - MAXIMUM size, in bytes, of the data to be returned
        callBack - EPI Callbackable object
      • delTerminal

        public void delTerminal()
        Sets the Call_Type of this object to EPI_DEL_TERMINAL.

        This method deletes a previously added terminal resource, identified by its termIndex.

      • delTerminal

        public void delTerminal(int itermIndex)
        Sets the Call_Type of this object to EPI_DEL_TERMINAL and also sets the termIndex associated with this object.

        This method deletes a previously added terminal resource, identified by its termIndex.

        The CICS TG will not consider that the deletion has completed until it has processed the corresponding CICS_EPI_EVENT_END_TERM event. The terminal index remains allocated until a getEvent call completes successfully and the CICS_EPI_EVENT_END_TERM event is received.

        Parameters:
        itermIndex - Terminal Index of terminal to be deleted
      • purgeTerminal

        public void purgeTerminal()
        Sets the Call_Type of this object to EPI_PURGE_TERMINAL.

        This method deletes a previously added terminal resource, identified by its termIndex. However it does not purge any outstanding ATI requests queued against a terminal.

        The CICS TG will not consider that the deletion has completed until it has processed the corresponding CICS_EPI_EVENT_END_TERM event. The terminal index remains allocated until a getEvent call completes successfully and the CICS_EPI_EVENT_END_TERM event is received. This purge function does not cancel ATI requests queued against the terminal.

      • purgeTerminal

        public void purgeTerminal(int itermIndex)
        Sets the Call_Type of this object to EPI_PURGE_TERMINAL and also sets the termIndex associated with this object.

        This method deletes a previously added terminal resource, identified by its termIndex. The application should not consider the deletion complete until it receives the corresponding CICS_EPI_EVENT_END_TERM event. The terminal index remains allocated until a getEvent call completes successfully and retrieves the CICS_EPI_EVENT_END_TERM event.

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

        Parameters:
        itermIndex - Terminal Index of terminal to be purged
      • alterSecurity

        public void alterSecurity(java.lang.String strUserid,
                         java.lang.String strPassword)
        Sets the Call_Type of this object to EPI_SET_SECURITY and also sets the userid and password associated with this object.

        This method defines a request which allows the userid and password associated with the currently installed terminal to be changed.

        A null for userid or password is allowed and results in a blank string

        If strUserid length exceeds EPI_USERID_MAX or strPassword length exceeds EPI_PASSWORD_MAX, the string will be truncated.

        Parameters:
        strUserid - New Userid to be assigned
        strPassword - New Password to be assigned
      • alterSecurity

        public void alterSecurity(java.lang.String strUserid,
                         java.lang.String strPassword,
                         int iTermIndex)
        Sets the Call_Type of this object to EPI_SET_SECURITY and also sets the userid and password associated with this object.

        This method defines a request which allows the userid and password associated with the currently installed terminal to be changed.

        A null for userid or password is allowed and results in a blank string

        If strUserid length exceeds EPI_USERID_MAX or strPassword length exceeds EPI_PASSWORD_MAX, the string will be truncated.

        Parameters:
        strUserid - New Userid to be assigned
        strPassword - New Password to be assigned
        iTermIndex - Terminal Index of terminal to be altered
©Copyright IBM Corp. 1994, 2013
Legal