C H A P T E R 9 |
External Presentation Interface (EPI) |
The External Presentation Interface (EPI) for Sun MTP is an API that allows a non-CICS application program to appear to Sun MTP as one or more standard 3270 terminals. The EPI application communicates with Sun MTP as if it is a normal 3270 terminal and allows you to
The EPI application is responsible for the presentation of the 3270 data it receives. It may present the data to a device by emulating a 3270 terminal or by any other means appropriate to the user.
This chapter describes EPI as C program function specifications and the data structures they require.
Examples that illustrate how to use EPI from the C programming language are found in the $INSTROOT\EXAMPLES directory, where $INSTROOT indicates the name of the directory where the Sun MTP Client was installed on your machine. The directory also contains a README file explaining its use and the necessary Sun MTP server COBOL source code.
EPI is a set of functions in a library that can be called from any program. These routines are a C language interface.
All applications must include cics_epi.h to obtain the definitions and prototypes described in this manual.
The EPI functions, CICS_EpiInitialize() and CICS_EpiTerminate(), initialize and terminate EPI, respectively.
The CICS_EpiInitialize() function must be called once per task to initialize the EPI interface. All other EPI calls are invalid before the initialization function is complete. Initialization is complete when the CICS_EpiInitialize() call returns with a good return code.
The CICS_EpiTerminate() function must be called when a process has completed using EPI, typically just before the task terminates. This terminate function cleanly terminates EPI.
Future compatibility between EPI versions is provided by the CICS_EpiInitialize() function, which requires a parameter that defines the version of EPI for which this application is coded.
After the application completes the initialization, it can install one or more EPI terminals, which appear to Sun MTP as 3270 terminals. The application must call the CICS_EpiAddTerminal() function once for each terminal to be added. This function returns a value that is used to identify it uniquely within the application.
To apply any EPI functions using this terminal, the application passes this TermIndex to the EPI functions.
When the application no longer needs a terminal, delete it by calling the CICS_EpiDelTerminal() function. After the deletion completes successfully, the TermIndex value becomes free and can be reused by EPI. However, the deletion does not complete until the application receives the CICS_EPI_EVENT_END_TERM event.
The delete function fails if the terminal is currently running a transaction. In this case, the function returns an error code.
To track information on a per terminal basis, the application can use a simple array indexing scheme., which uses the TermIndex value to maintain the corresponding terminal information.
The application can start transactions against any installed terminal. From the Sun MTP perspective, the transaction appears as if a terminal user entered a transaction on the screen and pressed an AID key.
The application calls the CICS_EpiStartTran() function to start a transaction. The CICS_EpiStartTran() parameters are the name of the transaction and the initial 3270 data associated with the transaction.
If the transaction name is not given, EPI determines the name of the required transaction from up to the first four data characters in the 3270 data following the AID sequence. This simplifies EPI applications that provide true 3270 terminal emulation. The initial 3270 data is not normally empty. It contains at least the AID byte for the 3270 key that causes the terminal input.
For information about the format of the 3270 datastream, refer to the IBM 3270 Information Display System Data Stream Programmers Reference.
A variety of events can affect an added terminal. The events are the result of actions within the remote system, not actions of the terminal user. When events occur, the EPI application is informed by EPI.
On receipt of event notification, the EPI application should make calls to the CICS_EpiGetEvent() function to retrieve a single event from the queue for processing. This function returns a data structure, CICS_EpiEventData_t, with information to indicate the event that occurred and any associated data. It also indicates if there are more events waiting in the queue. Refer to EPI Events for more information on the possible events and the information in the CICS_EpiEventData_t data structure.
If there are more events available for this terminal, the application should continue to call CICS_EpiGetEvent() until the event queue is empty. Failure to do so prevents the application from being notified of future events for the terminal.
The application should try to process events as quickly as possible. This synchronization prevents conditions in which the EPI state and the application state do not agree. When this mismatch occurs, the application receives an unexpected error return code when it tries to issue EPI functions.
Event notification varies on the supported platforms. The following sections describe these differences.
On Windows NT, event notification is performed through a callback mechanism. When there are events ready for a particular terminal, the callback routine specified on the CICS_EpiAddTerminal() call is initiated. This callback is on a separate thread owned by EPI; no EPI work should be performed from this thread. Normally, the callback routine must inform the main code that there is something ready using messages and events.
There are special considerations required to get the callback mechanism to work properly on Solaris. Sun MTP Client communicates with an application via named pipes. Since Sun MTP Client is single threaded, data can only be read from the pipe when an application calls into the ECI/EPI interface. It is only at this point that it is possible to perform callbacks. Thus, event notification callbacks are only performed while processing other ECI/EPI functions. This limitation can cause problems when designing an application that works effectively.
To simplify this process, use the KixCli_QueryFD() function, which returns a standard UNIX file descriptor (FD) that is the pipe used for communications. An application can use the select() function call to wait until there is information for the ECI/EPI to process. When the application is told that there is data, it can call into the ECI/EPI to process any callbacks.
The supplied sample, EPIEX2, shows how to fit this mechanism into a curses application that performs multiple concurrent units-of-work, while simultaneously servicing user input.
EPI generates either a CICS_EPI_EVENT_SEND or a CICS_EPI_EVENT_CONVERSE event when a transaction sends data to a terminal. The CICS_EPI_EVENT_SEND event does not require a reply from the terminal. The CICS_EPI_EVENT_CONVERSE event does require a reply from the terminal.
The EPI application replies by calling the CICS_EpiReply() function to provide the response data. Use this function to respond to the CICS_EPI_EVENT_CONVERSE event only; calling this function in response to any other event returns an error.
For information about the format of the 3270 datastream, refer to the IBM 3270 Information Display System Data Stream Programmers Reference.
EPI include files provide constants and data structures for using EPI. The following sections describe the constants, standard data types, and data structures.
EPI defines the following constants for use in EPI applications (#define statements in C):
EPI defines the following data types for use in EPI applications:
EPI defines the following data structures for use in EPI applications
This data structure contains the name and description of a remote Sun MTP region. The CICS_EpiListSystems() function returns information of this type.
typedef struct { cics_char_t SystemName[CICS_EPI_SYSTEM_MAX+1]; cics_char_t Description[CICS_EPI_DESCRIPTION_MAX+1]; } CICS_EpiSystem_t; |
Pass a pointer to this structure to the CICS_EpiAddTerminal() function. When the terminal install is complete, the structure contains details about the terminal.
Pass a pointer to this structure (with the Data and Size fields set) to the CICS_EpiGetEvent() function. If the function returns successfully, it returns this structure with details about the event. Not all fields are valid for all events; any invalid fields are set to zero or NULL bytes.
Index number for the terminal against which this event occurred. |
|
Specifies the event. See EPI Events for a description of the event indicators. |
|
Termination reason, if the event is a CICS_EPI_EVENT_END_TERM. |
|
Four-character string that specifies the transaction name. The string is padded with spaces and is terminated by a NULL byte. |
|
Four-character string that specifies the ABEND code. The string is padded with spaces and is terminated by a NULL byte. |
|
Pointer to a buffer that contains any terminal data stream associated with the event. |
|
Contains the maximum size of the buffer addressed by Data. When the CICS_EpiGetEvent() function returns, this field contains the actual length of the data returned. |
Pass a pointer to this structure as a parameter to the CICS_EpiGetSysError() function. If the function returns successfully, it returns this structure with details about the cause of a system error.
typedef struct { u_long_t Cause; u_long_t Value; char Msg[CICS_EPI_ERROR_MAX+1]; } CICS_EpiSysError_t; |
The possible values for the Cause field are
This type is used as a parameter to the CICS_EpiAddTerminal() function. It defines a function to be called when there is an EPI event outstanding.
typedef void (CICS_EpiCallback_t)(cics_ushort_t Trm); typedef CICS_EpiCallback_t *CICS_EpiNotify_t; |
This type defines the event codes that EPI generates. For additional information about each event code, see EPI Events.
typedef cics_ushort_t CICS_EpiEvent_t; |
This type defines the possible reason codes for a CICS_EPI_EVENT_END_TERM event. For more information about each reason code, see CICS_EPI_EVENT_END_TERM.
typedef cics_ushort_t CICS_EpiEnd_t; |
This type defines the possible values to pass to the CICS_EpiATIState() function. This function also returns these values when the function completes.
typedef cics_ushort_t CICS_EpiATIState_t; |
This type defines the possible values to pass to the CICS_EpiSenseCode() function. The CICS_EpiSenseCode() function performs no function, and is provided for compatibility only.
typedef cics_ushort_t CICS_EpiSenseCode_t; |
This type defines the possible values to pass to the CICS_EpiGetEvent() function. The value has no meaning but must be one of the defined values.
typedef cics_ushort_t CICS_EpiWait_t; |
The EPI application is responsible for collecting and processing all EPI events. When an event occurs against a terminal, EPI informs the application that there is an event outstanding.
When event notification is received, the EPI application calls CICS_EpiGetEvent() to retrieve the CICS_EpiEventData_t structure. This structure indicates the event that occurred and contains details about the event.
The following are the possible EPI events:
A Sun MTP transaction sent some 3270 data to a terminal and is not expecting a reply. However, the data should display. This is typically the result of an EXEC CICS SEND type command.
The following fields are complete in the CICS_EpiEventData_t structure for this event:
Buffer pointed to by this field that contains the data sent by the transaction. The first two bytes are the 3270 command and the WCC (Write Control Character). |
|
A Sun MTP transaction sent some 3270 data to a terminal and is expecting a reply. This is the result of an EXEC CICS RECEIVE type command or an EXEC CICS CONVERSE type command. Here, the application uses the CICS_EpiReply() call to return the reply data to Sun MTP.
The type of reply expected by Sun MTP depends on the 3270 command order in the first byte of the supplied Data field. If the 3270 command order is a Read Buffer command, Sun MTP expects the reply immediately. If the command is a Read Modified or Read Modified All, Sun MTP expects the reply when the user next presses an AID key. This event may occur with or without any associated data. If there is no data, the Size field is set to zero.
The following fields are completed in the CICS_EpiEventData_t structure for this event:
Buffer pointed to by this field that contains the data sent by the transaction. |
|
Length of the data in the Data buffer. If zero, it indicates that no data was sent, but a reply is expected. |
A Sun MTP transaction against a terminal is ended. If the transaction ends abnormally, the event may indicate the AbendCode. If the transaction finishes normally, the AbendCode field is four spaces. If the transaction is pseudo-conversational, the TransId field contains the name of the next transaction required. The application should start this transaction when the user next presses an AID key (use the CICS_EpiStartTran() function).
An application may only begin a transaction if no other transaction is running. The CICS_EPI_EVENT_END_TRAN event signals that EPI is in a state to accept a new transaction.
The following fields are in the CICS_EpiEventData_t structure for this event:
An Asynchronous Transaction Initiation (ATI) transaction is started against this terminal. If the terminal receives an ATI request while it is running another transaction, the request is held by EPI until the end of the current transaction. When the current transaction ends, the ATI transaction starts for the terminal and EPI generates this event to inform the application.
The CICS_EPI_EVENT_START_ATI event indicates an ATI transaction is started and the EPI state no longer allows transactions to start. If the application calls the CICS_EpiStartTran() function after EPI generates the CICS_EPI_EVENT_START_ATI event but before it is received, the start transaction function fails.
The following fields are in the CICS_EpiEventData_t structure for this event:
Name of the ATI transaction started. It is four characters and terminated with an extra NULL byte. |
This event indicates that a terminal no longer exists. The TermIndex for this terminal is no longer valid after this event is retrieved.
The following fields are in the CICS_EpiEventData_t structure for this event:
The EPI library includes the following functions that you can call from a C program:
The CICS_EpiInitialize function initializes EPI. You should call this function once per process; any other EPI calls before this function are invalid.
cics_sshort_t CICS_EpiInitialize(cics_ulong_t Version); |
This function terminates EPI. Call this function once per process, usually just before the process terminates. Any EPI calls made after this function are invalid. Calling this function does not delete any EPI terminals defined by the application. The application must issue the CICS_EpiDelTerminal() calls before terminating the interface.
cics_sshort_t CICS_EpiTerminate(void); |
This function obtains a list of possible candidate systems (Sun MTP regions) to which a terminal can be attached.
cics_sshort_t CICS_EpiListSystems (cics_char_t *NameSpace, cics_ushort_t *Systems, CICS_EpiSystem_t *List); |
This function installs a new terminal. It returns a TermIndex value to use on all further terminal-specific EPI calls. The index number is the next available small integer, starting at zero. The application must maintain a mapping between index numbers and terminals to process per-terminal information.
The following return codes are returned by CICS_EpiGetSysError() if CICS_EpiAddTerminal() fails while performing its asynchronous work:
This function deletes an installed EPI terminal. If the terminal was autoinstalled, its definition is deleted. However, the application cannot delete a terminal if the terminal is currently running a transaction. If the application calls this function while the terminal is processing a transaction, the function fails. When the current transaction finishes, the application can successfully call this function. The application should not consider the terminal completely deleted until it receives a good return code and the CICS_EPI_EVENT_END_TERM event.
cics_sshort_t CICS_EpiDelTerminal(cics_ushort_t TermIndex); |
This function starts a transaction for an installed terminal. If the transaction begins, no other start requests are accepted by EPI until the CICS_EPI_EVENT_END_TRAN event is generated.
The application may get an unexpected return code of CICS_EPI_ERR_ATI_ACTIVE. This can occur even if the application believes a terminal is not currently running a transaction. It means that an ATI request was started against the terminal and a CICS_EPI_EVENT_START_ATI event has been raised, but the application has not processed this event.
cics_sshort_t CICS_EpiStartTran (cics_ushort_t TermIndex, cics_char_t *TransId, cics_ubyte_t *Data, cics_ushort_t Size); |
This function sends data from a terminal to a Sun MTP transaction. It is used only for replying to a CICS_EPI_EVENT_CONVERSE event.
cics_sshort_t CICS_EpiReply (cics_ushort_t TermIndex, cics_ubyte_t *Data, cics_ushort_t Size); |
Pointer to a buffer of 3270 data to be sent to the transaction. This field cannot be a NULL pointer; it must contain at least the 3270 AID byte that causes the terminal read. |
|
This function allows the application to query and change the terminal handling of ATI requests. If ATI requests are enabled (CICS_EPI_ATI_ON) and an ATI request is issued, EPI automatically starts the request as soon as the terminal is available. If ATI requests are held (CICS_EPI_ATI_HOLD), any ATI requests are queued and started when ATI requests are enabled.
EPI always begins in the CICS_EPI_ATI_HOLD state. The application can change the handling of ATI requests when it is ready to allow ATI processing and provided the terminal definition allows ATI requests.
cics_sshort_t CICS_EpiATIState (cics_ushort_t TermIndex, CICS_EpiATIState_t *ATIState); |
One of CICS_EPI_ATI_ON, CICS_EPI_ATI_HOLD, CICS_EPI_ATI_QUERY, as defined in CICS_EpiATIState_t.On entry to this function, this field contains the required new ATI state. On exit from this function, this field contains the previous state. |
Call this function when an application detects an error on the datastream sent to it.
Note - This function is retained only for compatibility and is ignored. |
cics_sshort_t CICS_EpiSenseCode (cics_ushort_t TermIndex, CICS_EpiSenseCode_t SenseCode); |
Sense Code failure reason, one of CICS_EPI_ATI_OPCHECK or CICS_EPI_ATI_REJECT, as defined in CICS_EpiSenseCode_t. |
This function retrieves an event from the event queue for processing.
cics_sshort_t CICS_EpiGetEvent (cics_ushort_t TermIndex, CICS_EpiWait_t Wait, CICS_EpiEventData_t *Event); |
This function obtains detailed error information about the last error that occurred. Error information is saved by EPI when any EPI command failed with a return code of CICS_EPI_ERR_FAILED
If an EPI function gave this return code, call this function specifying the TermIndex relevant to the original EPI request. The value returned in the SysErr parameter further describes the return code from any other EPI function.The values are operating system and environment specific and are explained in the documentation provided for each environment.
cics_sshort_t CICS_EpiGetSysError(cics_ushort_t TermIndex, CICS_EpiSysError_t *SysErr); |
When the values returned in the SysErr parameter are relevant, the following values for the Cause field have the listed meanings.
This function supplies limited information about a terminal. When a TermIndex is specified, this function returns the name of the system to which the terminal is attached.
Copyright © 2003, Sun Microsystems, Inc. All rights reserved.