9 - C H A P T E R -

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

Log on terminals

Start transactions

Send and receive standard 3270 data streams to and from those transactions

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.

EPI Examples

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.

Developing an EPI Application

EPI is a set of functions in a library that can be called from any program. These routines are a C language interface.

For Windows

The ECI/EPI code is in CCLAPI32.DLL

Link applications with CCLWIN32.LIB

For Solaris

The ECI/EPI code is in libcclapi.so

Link applications with libcclapi.so

All applications must include cics_epi.h to obtain the definitions and prototypes described in this manual.

Initializing and Terminating EPI

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.

Adding and Deleting EPI Terminals

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.

Starting Transactions

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.

Processing Events

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.

Event Notification on Windows

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.

Event Notification on Solaris

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.

Sending and Receiving Data

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 Constants and Data Structures

EPI include files provide constants and data structures for using EPI. The following sections describe the constants, standard data types, and data structures.

Constants

EPI defines the following constants for use in EPI applications (#define statements in C):

`CICS_EPI_SYSTEM_MAX`	`8`
`CICS_EPI_DESCRIPTION_MAX`	`60`
`CICS_EPI_NETNAME_MAX`	`8`
`CICS_EPI_TRANSID_MAX`	`4`
`CICS_EPI_ABEND_MAX`	`4`
`CICS_EPI_DEVTYPE_MAX`	`16`
`CICS_EPI_ERROR_MAX`	`60`
`CICS_EPI_TERM_INDEX_NONE`	`0xFFFF`

Standard Data Types

EPI defines the following data types for use in EPI applications:

`cics_char_t`	character type
`cics_sbyte_t`	signed 8-bit integer
`cics_sshort_t`	signed 16-bit integer
`cics_slong_t`	signed 32-bit integer
`cics_ubyte_t`	unsigned 8-bit integer
`cics_ushort_t`	unsigned 16-bit integer
`cics_ulong_t`	unsigned 32-bit integer
`cics_ptr_t`	general pointer type
`cics_shandle_t`	general 16-bit handle
`cics_lhandle_t`	general 32-bit handle

Data Structures

EPI defines the following data structures for use in EPI applications

`CICS_EpiSystem_t`

This data structure contains the name and description of a remote Sun MTP region. The CICS_EpiListSystems() function returns information of this type.

C Definition

typedef struct

	cics_char_t   SystemName[CICS_EPI_SYSTEM_MAX+1];

	cics_char_t   Description[CICS_EPI_DESCRIPTION_MAX+1];

} CICS_EpiSystem_t;

where:

`SystemName`	Name of an Sun MTP region. Pass this string as a parameter to the `CICS_EpiAddTerminal()` function to identify the region to which the terminal should attach. This string is padded with NULL bytes and is terminated by an extra NULL byte.
`Description`	Brief description of the system. This string is padded with NULL bytes and is terminated by an extra NULL byte.

`CICS_EpiDetails_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.

C Definition

typedef struct

	cics_char_t    SystemName[CICS_EPI_SYSTEM_MAX+1];

	cics_char_t    Description[CICS_EPI_DESCRIPTION_MAX+1];

	cics_char_t    NetName[CICS_EPI_NETNAME_MAX+1];

	cics_sshort_t  NumLines;

	cics_sshort_t  NumColumns;

	cics_ushort_t  MaxData;

	cics_sshort_t  ErrLastLine;

	cics_sshort_t  ErrIntensify;

	cics_sshort_t  ErrColor;

	cics_sshort_t  ErrHilight;

	cics_sshort_t  Hilight;

	cics_sshort_t  Color;

	cics_sshort_t  Printer;

} CICS_EpiDetails_t;

where:

`SystemName`	Name of a Sun MTP region. Pass this string as a parameter to the `CICS_EpiAddTerminal()` function to identify the region to which the terminal should attach. This string is padded with NULL bytes and is terminated by an extra NULL byte.
`Description`	Brief description of the system. This string is padded with NULL bytes and is terminated by an extra NULL byte.
`NetName`	An 8-character string that specifies the VTAM-style `NetName` by which the terminal gets installed. This string is padded with NULL bytes and is terminated by an extra NULL byte.
`NumLines`	Contains the number of lines supported by the terminal.
`NumColumns`	Contains the number of columns supported by the terminal.
`MaxData`	Contains the maximum possible size of the data Sun MTP sends to the terminal.
`ErrLastLine`	Non-zero if the terminal displays error messages on its last line.
`ErrIntensify`	Non-zero if the terminal displays intensified error messages.
`ErrColor`	Contains the 3270 attribute defining the color value for displaying error messages.
`ErrHilight`	Contains the 3270 attribute defining the highlight value for displaying error messages.
`Hilight`	Non-zero if the terminal supports extended highlighting.
`Color`	Non-zero if the terminal supports color.
`Printer`	Non-zero if the terminal is a printer.

`CICS_EpiEventData_t`

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.

C Definition

typedef struct

	u_short_t         TermIndex;

	CICS_EpiEvent_t   Event;

	CICS_EpiEnd_t     EndReason;

	char              TransId[CICS_EPI_TRANSID_MAX+1];

	char              AbendCode[CICS_EPI_ABEND_MAX+1];

	u_byte_t *        Data;

	u_short_t         Size;

} CICS_EpiEventData_t;

where:

`TermIndex`	Index number for the terminal against which this event occurred.
`Event`	Specifies the event. See EPI Events for a description of the event indicators.
`EndReason`	Termination reason, if the event is a `CICS_EPI_EVENT_END_TERM`.
`TransId[]`	Four-character string that specifies the transaction name. The string is padded with spaces and is terminated by a NULL byte.
`AbendCode[]`	Four-character string that specifies the `ABEND` code. The string is padded with spaces and is terminated by a NULL byte.
`Data`	Pointer to a buffer that contains any terminal data stream associated with the event.
`Size`	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.

`CICS_EpiSysError_t`

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.

C Definition

typedef struct

	u_long_t   Cause;

	u_long_t   Value;

	char       Msg[CICS_EPI_ERROR_MAX+1];

} CICS_EpiSysError_t;

where:

`Cause`	Operating environment specific value that indicates the cause of the last error.
`Value`	Operating environment specific value that indicates the nature of the last error.
`Msg`	Text message that may describe the last error. This string is padded with NULL bytes; EPI terminates it with an extra NULL byte. If no message is available, the string is all NULLS.

The possible values for the Cause field are

CICS_EPI_SYSERROR_UNEXPECTED_DATASTREAM

A datastream was received from the Sun MTP region that Sun MTP Client could not decode.

CICS_EPI_SYSERROR_NO_MEMORY

Sun MTP Client encountered memory allocation problems.

CICS_EPI_SYSERROR_DUPLICATE_NETNAME

The NetName specified in the add terminal command was already in use.

CICS_EPI_SYSERROR_UNKNOWN_NETNAME

NetName specified in the add terminal command was unknown to the end system.

CICS_EPI_SYSERROR_UNKNOWN_DEVTYPE

DevType specified in the add terminal command was unknown to the end system.

CICS_EPI_SYSERROR_INVALID_TPNAME

The end system did not recognize the terminal installation transaction.

CICS_EPI_SYSERROR_UNEXPECTED_ERROR

An internal function has produced an unexpected error.

CICS_EPI_SYSERROR_UNKNOWN_SYSTEM

System specified in the add terminal command is not defined.

CICS_EPI_SYSERROR_TERMINAL_OUT_OF_SERVICE

Could not install the terminal into the end system because its definition is set out of service.

CICS_EPI_SYSERROR_SYSTEM_UNAVAILABLE

System specified in the add terminal command is unavailable at this time.

CICS_EPI_SYSERROR_INTERNAL_LOGIC_ERROR

Internal logic error in Sun MTP Client.

CICS_EPI_SYSERROR_AUTOINSTALL_FAILED

Autoinstall process failed on the Sun MTP region.

CICS_EPI_SYSERROR_TERM_INSTALL_FAILED

The terminal install process failed on the Sun MTP region.

`CICS_EpiNotify_t`

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.

C Definition

typedef void (CICS_EpiCallback_t)(cics_ushort_t Trm);

typedef CICS_EpiCallback_t *CICS_EpiNotify_t;

`CICS_EpiEvent_t`

This type defines the event codes that EPI generates. For additional information about each event code, see EPI Events.

C Definition

typedef cics_ushort_t CICS_EpiEvent_t;

Values

CICS_EPI_EVENT_SEND

CICS_EPI_EVENT_CONVERSE

CICS_EPI_EVENT_END_TRAN

CICS_EPI_EVENT_START_ATI

CICS_EPI_EVENT_END_TERM

`CICS_EpiEnd_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.

C Definition

typedef cics_ushort_t CICS_EpiEnd_t;

Values

CICS_EPI_END_SIGNOFF

CICS_EPI_END_SHUTDOWN

CICS_EPI_END_OUTSERVICE

CICS_EPI_END_UNKNOWN

CICS_EPI_END_FAILED

`CICS_EpiATIState_t`

This type defines the possible values to pass to the CICS_EpiATIState() function. This function also returns these values when the function completes.

C Definition

typedef cics_ushort_t CICS_EpiATIState_t;

Values

CICS_EPI_ATI_ON

EPI processes Asynchronous Transaction Initiation (ATI) requests in the normal manner.

CICS_EPI_ATI_HOLD

EPI queues all ATI requests until CICS_EPI_ATI_ON is set.

CICS_EPI_ATI_QUERY

The ATI request status of EPI is unchanged. Use this value to query the current setting.

`CICS_EpiSenseCode_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.

C Definition

typedef cics_ushort_t CICS_EpiSenseCode_t;

Values

CICS_EPI_SENSE_OPCHECK

EPI detects an error in the 3270 datastream.

CICS_EPI_SENSE_REJECT

EPI detects an invalid 3270 command.

`CICS_EpiWait_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.

C Definition

typedef cics_ushort_t CICS_EpiWait_t;

Values

CICS_EPI_WAIT

CICS_EPI_NOWAIT

EPI Events

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:

CICS_EPI_EVENT_SEND

CICS_EPI_EVENT_CONVERSE

CICS_EPI_EVENT_END_TRAN

CICS_EPI_EVENT_START_ATI

CICS_EPI_EVENT_END_TERM

`CICS_EPI_EVENT_SEND`

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:

`Event`	`CICS_EPI_EVENT_SEND`
`Data`	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).
`Size`	Length of the data in the `Data` buffer.

`CICS_EPI_EVENT_CONVERSE`

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:

`Event`	`CICS_EPI_EVENT_CONVERSE`
`Data`	Buffer pointed to by this field that contains the data sent by the transaction.
`Size`	Length of the data in the `Data` buffer. If zero, it indicates that no data was sent, but a reply is expected.

`CICS_EPI_EVENT_END_TRAN`

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:

`Event`	`CICS_EPI_EVENT_END_TRAN`
`TransId`	If the transaction is pseudo-conversational, this is the name of the next transaction to start. The name is four characters and is terminated with an extra NULL byte. If there is no next transaction, the field is all NULL bytes.
`AbendCode`	If the transaction ends abnormally, this field may contain the `AbendCode`, which is four characters terminated with an extra NULL byte. If the transaction finishes successfully, it contains four spaces and a NULL byte.

`CICS_EPI_EVENT_START_ATI`

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:

`Event`	`CICS_EPI_EVENT_START_ATI`
`TransId`	Name of the ATI transaction started. It is four characters and terminated with an extra NULL byte.

`CICS_EPI_EVENT_END_TERM`

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:

Event

CICS_EPI_EVENT_END_TERM

EndReason

Contains one of the following reasons why the terminal was ended or no longer exists

CICS_EPI_END_SIGNOFF

Terminal is signed-off; possibly the result of calling CICS_EpiDelTerminal().

CICS_EPI_END_SHUTDOWN

Sun MTP is shutting down.

CICS_EPI_END_OUTSERVICE

Terminal is switched to out-of-service.

CICS_EPI_END_UNKNOWN

Unexpected error occurred.

CICS_EPI_END_FAILED

Failure to delete a terminal occurred.

EPI Functions

The EPI library includes the following functions that you can call from a C program:

CICS_EpiInitialize()

CICS_EpiTerminate()

CICS_EpiListSystems()

CICS_EpiAddTerminal()

CICS_EpiDelTerminal()

CICS_EpiGetSysError()

`CICS_EpiInitialize()`

The CICS_EpiInitialize function initializes EPI. You should call this function once per process; any other EPI calls before this function are invalid.

Format

cics_sshort_t CICS_EpiInitialize(cics_ulong_t Version);

where:

Version

Version of the EPI library for which the application is coded. This provides future compatibility with EPI library versions.

For this version of EPI, set this parameter to the constant CICS_EPI_VERSION_101.

Return Codes

CICS_EPI_NORMAL

Successful completion.

CICS_EPI_ERR_FAILED

EPI is unable to initialize the interface.

CICS_EPI_ERR_VERSION

EPI cannot support the version requested.

CICS_EPI_ERR_IS_INIT

EPI is already initialized for this process.

`CICS_EpiTerminate()`

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.

Format

cics_sshort_t CICS_EpiTerminate(void);

Return Codes

CICS_EPI_NORMAL

Successful completion.

CICS_EPI_ERR_NOT_INIT

Initialization is not completed.

CICS_EPI_ERR_FAILED

Unable to terminate EPI.

`CICS_EpiListSystems()`

This function obtains a list of possible candidate systems (Sun MTP regions) to which a terminal can be attached.

Format

cics_sshort_t CICS_EpiListSystems  (cics_char_t    *NameSpace,

cics_ushort_t                                      *Systems,

CICS_EpiSystem_t                                   *List);

where:

`Namespace`	parameter is ignored but should be set to a NULL pointer.
`Systems`	Set to the maximum number of `CICS_EpiSystem_t` structures that EPI may return. When the function returns, this field contains the actual number of systems found.
`List`	Array of `CICS_EpiSystem_t` data structures. The function fills in these structures and returns them to the application. The caller provides the storage for the array and sets the `Systems` parameter to indicate the maximum size of the array.

Return Codes

CICS_EPI_NORMAL

Successful completion.

CICS_EPI_ERR_NOT_INIT

Initialization is not completed; call CICS_EpiInitialize().

CICS_EPI_ERR_FAILED

Unable to find candidate systems.

CICS_EPI_ERR_NO_SYSTEMS

EPI fails to find a candidate system. The return value in the Systems field is zero.

CICS_EPI_ERR_MORE_SYSTEMS

Not enough space in the array to store all the candidate systems. The actual number of systems is found in the Systems field. Use this to reallocate enough storage for all the candidate systems and retry the function.

`CICS_EpiAddTerminal()`

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.

Format

cics_sshort_t CICS_EpiAddTerminal (cics_char_t       *NameSpace,

                                   cics_char_t       *System,

                                   cics_char_t       *NetName,

                                   cics_char_t       *DevType,

                                   CICS_EpiNotify_t   NotifyFn,

                                   CICS_EpiDetails_t *Details,

                                   cics_ushort_t     *TermIndex);

where:

`Namespace`	Parameter is ignored but should be set to a NULL pointer.
`System`	Name of the system to which the terminal is to be attached.This name should match one of the systems returned from the `CICS_EpiListSystems()` function call. If a string of 0 length is specified, the default system is used as specified in the `KIXCLI.INI` configuration file.This is a pointer to a NULL terminated string.
`NetName`	VTAM-style net name for the terminal found in the Sun MTP TCT. This is a pointer to a string that is padded with NULL bytes and terminated with an extra NULL byte. If this parameter is set to a NULL pointer, a default is used. If this parameter is provided, it must be unique and must match one of the net names in the terminal definitions listed in the system's terminal database. The terminal is auto-installed if no `NetName` is specified.
`DevType`	Pointer to a string that specifies the model terminal. This string is padded with NULL bytes and terminated with an extra NULL byte. This parameter is ignored if the `NetName` parameter is not NULL. If this field is set to a NULL pointer, the default model IBM-3278-2 is used. The names for the terminal models are system specific, but for Sun MTP, the valid models are: IBM-3278-2, IBM-3278-2-E IBM-3278-4, IBM-3278-4-E IBM-3278-5, IBM-3278-5-E IBM-3287 The `-E` suffix indicates that the terminal has extended visual attributes.
`NotifyFn`	Address of a routine to call when an EPI event occurs for this terminal.
`Details`	Pointer to a structure that EPI fills with details about the terminal that was installed. An application can safely use and discard this storage on receipt of the `CICS_EPI_WIN_INSTALLED` message.
`TermIndex`	Index number of the terminal that was installed. Use this index number on all other EPI functions that are specific to this terminal. The index generated is the first available integer starting from 0.

Return Codes

CICS_EPI_NORMAL

Successful completion.

CICS_EPI_ERR_NOT_INIT

Initialization is not completed.

CICS_EPI_ERR_FAILED

Unable to install the terminal.

CICS_EPI_ERR_SYSTEM

Name specified in the System parameter does not exist.

CICS_EPI_ERR_MAX_TERMS

EPI maximum number of terminals supported is reached.

The following return codes are returned by CICS_EpiGetSysError() if CICS_EpiAddTerminal() fails while performing its asynchronous work:

CICS_EPI_ERR_SYSTEM

Name specified in the System parameter does not exist.

CICS_EPI_ERR_MAX_TERMS

EPI maximum number of terminals supported is reached.

`CICS_EpiDelTerminal()`

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.

Format

cics_sshort_t CICS_EpiDelTerminal(cics_ushort_t TermIndex);

where:

TermIndex

Index number of the terminal to delete.

Return Codes

CICS_EPI_NORMAL

Successful completion.

CICS_EPI_ERR_NOT_INIT

Initialization is not completed.

CICS_EPI_ERR_FAILED

Unable to delete the terminal.

CICS_EPI_ERR_BAD_INDEX

TermIndex parameter does not represent a valid terminal.

CICS_EPI_ERR_TRAN_ACTIVE

A transaction is currently running against the terminal.

`CICS_EpiStartTran()`

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.

Format

cics_sshort_t CICS_EpiStartTran (cics_ushort_t  TermIndex,

                                 cics_char_t    *TransId,

                                 cics_ubyte_t   *Data,

                                 cics_ushort_t  Size);

where:

`TermIndex`	Index number of the terminal to run the transaction.
`TransId`	Transaction code to run against the terminal. This field is a pointer to a string that is padded with spaces and terminated with an extra NULL byte. If the field is a NULL pointer, EPI attempts to extract the correct transaction code from the Data buffer. It does this by examining the first byte of the data and skipping any 3270 control codes to find the start of the user data. It copies up to the next four characters until either another 3270 control code is found or no more data is available. The result is padded with spaces to four characters. To start a continuing portion of a pseudo-conversational transaction, this field must contain the `TransId` returned when the `CICS_EPI_EVENT_END_TRAN` event occurred.
`Data`	Pointer to the initial 3270 data buffer associated with the transaction. This parameter cannot be a NULL pointer; it must contain at least the 3270 AID key that caused the terminal read.
`Size`	Number of bytes in the `Data` buffer.

Return Codes

CICS_EPI_NORMAL

Successful completion.

CICS_EPI_ERR_NOT_INIT

Initialization is not completed.

CICS_EPI_ERR_FAILED

Unable to start the transaction.

CICS_EPI_ERR_BAD_INDEX

TermIndex parameter does not represent a valid terminal.

CICS_EPI_ERR_TTI_ACTIVE

A TTI transaction is already active for this terminal.

CICS_EPI_ERR_ATI_ACTIVE

An ATI transaction is active for this terminal.

CICS_EPI_ERR_NO_DATA

No initial data is provided.

`CICS_EpiReply()`

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.

Format

cics_sshort_t CICS_EpiReply  (cics_ushort_t  TermIndex,

                              cics_ubyte_t   *Data,

                              cics_ushort_t  Size);

where:

`TermIndex`	Index number of the terminal that is sending the data.
`Data`	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.
`Size`	Size of the `Data` buffer.

Return Codes

CICS_EPI_NORMAL

Successful completion.

CICS_EPI_ERR_NOT_INIT

Initialization is not completed.

CICS_EPI_ERR_FAILED

Unable to send the reply data.

CICS_EPI_ERR_BAD_INDEX

TermIndex parameter does not represent a valid terminal.

CICS_EPI_ERR_NO_CONVERSE

No CICS_EPI_EVENT_CONVERSE event is outstanding for the terminal.

CICS_EPI_ERR_NO_DATA

No reply data is provided.

`CICS_EpiATIState()`

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.

Format

cics_sshort_t CICS_EpiATIState   (cics_ushort_t  TermIndex,

              CICS_EpiATIState_t  *ATIState);

where:

`TermIndex`	Index number of the terminal.
`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.

Return Codes

CICS_EPI_NORMAL

Successful completion.

CICS_EPI_ERR_NOT_INIT

Initialization is not completed; call CICS_EpiInitialize().

CICS_EPI_ERR_FAILED

Unable to set or query the ATI state.

CICS_EPI_ERR_BAD_INDEX

TermIndex parameter does not represent a valid terminal.

CICS_EPI_ATI_STATE

An invalid ATIState was given.

`CICS_EpiSenseCode()`

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.

Format

cics_sshort_t CICS_EpiSenseCode (cics_ushort_t        TermIndex,

                                 CICS_EpiSenseCode_t  SenseCode);

where:

`TermIndex`	Index number of the terminal.
`SenseCode`	Sense Code failure reason, one of `CICS_EPI_ATI_OPCHECK` or `CICS_EPI_ATI_REJECT`, as defined in CICS_EpiSenseCode_t.

Return Codes

CICS_EPI_NORMAL

Successful completion.

CICS_EPI_ERR_NOT_INIT

Initialization is not completed.

`CICS_EpiGetEvent()`

This function retrieves an event from the event queue for processing.

Format

cics_sshort_t CICS_EpiGetEvent      (cics_ushort_t  TermIndex,

              CICS_EpiWait_t         Wait,

              CICS_EpiEventData_t    *Event);

where:

TermIndex

Index number of the terminal for which to obtain an event. This can be the constant CICS_EPI_TERM_INDEX_NONE to indicate that the next event for any registered terminal is to be returned. In this case, the application should examine the TermIndex field in the returned CICS_EpiEventData_t structure to determine the relevant terminal.

Wait

Ignored, but must be set to either of the following:

CICS_EPI_WAIT

CICS_EPI_NOWAIT

Event

Pointer to a structure that contains details of the event that occurred.

The Data field of the structure points to the data buffer that is updated by any terminal datastream for the event.

The Size field indicates the maximum size of the data buffer and is updated to contain the actual length of the data returned.

Return Codes

CICS_EPI_NORMAL

Successful completion.

CICS_EPI_ERR_NOT_INIT

Initialization is not completed.

CICS_EPI_ERR_FAILED

Unable to get next event.

CICS_EPI_ERR_BAD_INDEX

The TermIndex parameter does not represent a valid terminal.

CICS_EPI_ERR_WAIT

Wait parameter is invalid.

CICS_EPI_ERR_NO_EVENT

No events are outstanding for this terminal.

CICS_EPI_ERR_MORE_DATA

Data buffer is insufficient to contain the terminal's data; the data is truncated.

CICS_EPI_ERR_MORE_EVENTS

An event is successfully obtained, but more events against this terminal are outstanding.

`CICS_EpiGetSysError()`

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.

Format

cics_sshort_t CICS_EpiGetSysError(cics_ushort_t      TermIndex,

                                  CICS_EpiSysError_t *SysErr);

where:

TermIndex

Index number of the terminal for which to obtain the additional error information. This can be the constant CICS_EPI_TERM_INDEX_NONE to indicate that further error information is required from the CICS_EpiInitialize(), CICS_EpiTerminate(), CICS_EpiListSystems(), or CICS_EpiAddTerminal() functions.

SysErr

Pointer to a CICS_EpiSysError_t structure that contains the system error information.The values in the Cause and Value fields of the SysErr structure can be used to further qualify the return code for an EPI function.

The Msg field returns an operating environment-specific text message describing the error that occurred, if available.

Return Codes

CICS_EPI_NORMAL

Successful completion.

CICS_EPI_ERR_NOT_INIT

Initialization is not completed.

CICS_EPI_ERR_BAD_INDEX

TermIndex parameter does not represent a valid terminal.

CICS_EPI_ERR_FAILED

Unable to obtain the SysErr information.

Other

Return code from the command that caused the last error. Refer to the sections on the original calls to decide on the meaning of these values. This is especially relevant to the CICS_EpiAddTerminal() function.

When the values returned in the SysErr parameter are relevant, the following values for the Cause field have the listed meanings.

CICS_EPI_SYSERROR_UNEXPECTED_DATASTREAM

Sun MTP Client received a datastream from Sun MTP that it could not decode.

CICS_EPI_SYSERROR_NO_MEMORY

Sun MTP Client was unable to obtain memory for its internal processing.

CICS_EPI_SYSERROR_DUPLICATE_NETNAME

NetName specified on the CICS_EpiAddTerminal() call is already being used.

CICS_EPI_SYSERROR_UNKNOWN_NETNAME

NetName specified on the CICS_EpiAddTerminal() call is unknown to the Sun MTP region to which you are communicating.

CICS_EPI_SYSERROR_UNKNOWN_DEVTYPE

DevType specified on the CICS_EpiAddTerminal() call is unknown to the Sun MTP region to which you are communicating.

CICS_EPI_SYSERROR_INVALID_TPNAME

The terminal install transaction CTIN is not available on the remote Sun MTP region.

CICS_EPI_SYSERROR_UNEXPECTED_ERROR

An internal error has occurred.

CICS_EPI_SYSERROR_UNKNOWN_SYSTEM

System specified was unknown to Sun MTP Client.

CICS_EPI_SYSERROR_TERM_OUT_OF_SERVICE

Terminal corresponding to the specified NetName is set out of service.

CICS_EPI_SYSERROR_SYSTEM_UNAVAILABLE

Cannot access the specified system at the present time.

CICS_EPI_SYSERROR_INTERNAL_LOGIC_ERROR

An internal error has occurred.

CICS_EPI_SYSERROR_AUTOINSTALL_FAILED

Terminal autoinstall failed for an unknown reason.

CICS_EPI_SYSERROR_TERM_INSTALL_FAILED

Terminal install failed for an unknown reason.

`CICS_EpiInquireSystem()`

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.

Format

cics_sshort_t CICS_EpiInquireSystem  (cics_ushort_t  TermIndex,

                                      cics_char_t    *System);

where:

`TermIndex`	Index number of the terminal for which system information is required.
`System`	Pointer to a buffer that contains the name of the system to which the `TermIndex` is connected.

Return Codes

CICS_EPI_NORMAL

Successful completion.

CICS_EPI_ERR_NOT_INIT

Initialization is not completed. Call CICS_EpiInitialize().

CICS_EPI_ERR_BAD_INDEX

TermIndex parameter does not represent a valid terminal.

CICS_EPI_ERR_FAILED

Unable to obtain system information.