OS/2 Shareware BBS: 10 Tools/10-Tools.zip/cicsprog.zip/DFHZAD.INF

OS/2 Help File | 1999-02-28 | 242KB | 7,519 lines

ΓòÉΓòÉΓòÉ 1. CICS Family: Client/Server Programming ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 2. Version Notice ΓòÉΓòÉΓòÉ

First edition (January, 1995)

This edition applies to the following releases of the IBM licensed program
Customer Information Control System (CICS):

o IBM CICS Client for DOS, Version 1, program number 5622-543

o IBM CICS Client for OS/2, Version 1, program number 5622-543

o IBM CICS Client for Windows, Version 1, program number 5622-543

o IBM CICS Client for Macintosh, Version 1, program number 5622-543

o IBM CICS for OS/2, Version 2.0.1, program number 5648-036

o IBM Transaction Server for OS/2 Warp, Version 4, program number 5622-808

o IBM CICS for Windows NT, Version 2, program number 5622-347

o IBM CICS Client for Sun Systems, Release 1, program number 5765-290

o IBM AIX CICS/6000, Version 1.2, program number 5765-148

o IBM AIX Client for CICS/6000, Version 1.2, program number 5765-152

o IBM CICS for AIX Version 2.1, program number 5765-553

It will also apply to any subsequent versions, releases, and modifications
until otherwise indicated in new editions. Consult the latest edition of the
applicable IBM system bibliography for current information on these products.

Order publications through your IBM representative or the IBM branch office
serving your locality. Publications are not stocked at the address given below.

A form for reader's comments appears at the back of this publication. If the
form has been removed, address your comments to:

IBM United Kingdom Laboratories Limited, Information Development,
Mail Point 095, Hursley Park, Winchester, Hampshire, England, SO21 2JN.

When you send information to IBM, you grant IBM a nonexclusive right to use or
distribute the information in any way it believes appropriate without incurring
any obligation to you.

(c) Copyright International Business Machines Corporation 1989, 1996. All
rights reserved.

Note to U.S. Government Users - Documentation related to restricted rights -
Use, duplication, or disclosure is subject to restrictions set forth in GSA ADP
Schedule Contract with IBM Corp.


ΓòÉΓòÉΓòÉ 3. Notices ΓòÉΓòÉΓòÉ

The following paragraph does not apply in any country where such provisions are
inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS"
WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A
PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied
warranties in certain transactions, therefore this statement may not apply to
you.

References in this publication to IBM products, programs, or services do not
imply that IBM intends to make these available in all countries in which IBM
operates.

Any reference to an IBM licensed program or other IBM product in this
publication is not intended to state or imply that only IBM's program or other
product may be used. Any functionally equivalent program that does not infringe
any of IBM's intellectual property rights may be used instead of the IBM
product. Evaluation and verification of operation in conjunction with other
products, except those expressly designated by IBM, is the user's
responsibility.

Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact Laboratory Counsel, MP151,
IBM United Kingdom Laboratories, Hursley Park, Winchester, Hampshire, England
SO21 2JN. Such information may be available, subject to appropriate terms and
conditions, including in some cases, payment of a fee.

IBM may have patents or pending patent applications covering subject matter in
this document. The furnishing of this document does not give you any license to
these patents. You can send license inquiries, in writing, to the IBM Director
of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood, New York 10594,
U.S.A.


ΓòÉΓòÉΓòÉ 3.1. Programming interface information ΓòÉΓòÉΓòÉ

This book is intended to help you to write application programs that use the
features provided by various members of the CICS family. This book documents
General-use Programming Interface and Associated Guidance Information provided
by various members of the CICS family.

General-use programming interfaces allow the customer to write programs that
obtain the services of various members of the CICS family.


ΓòÉΓòÉΓòÉ 3.2. Trademarks and service marks ΓòÉΓòÉΓòÉ

The following terms, used in this publication, are trademarks or service marks
of IBM Corporation in the United States or other countries or both:

CICS             CICS/ESA          CICS/MVS
CICS OS/2          CICS/VSE          CICS/400
CICS/6000          IBM             OS/2
Presentation Manager     AIX             IBMLink
VisualAge

The following terms used in this publication are trademarks of other companies:

Microsoft Corporation:    Microsoft          Windows
              Microsoft Windows      Windows NT
Sun Systems:         SunOS            Sun
Apple Computer Corp.:    Macintosh          Apple Macintosh
Open Software Foundation:  Motif
Novell Inc.:         Open Look
Hewlett-Packard Company:   HP-UX            HP 9000
Micro Focus Limited:     Micro Focus         Micro Focus Object COBOL


ΓòÉΓòÉΓòÉ 4. Summary of changes ΓòÉΓòÉΓòÉ

Information about ECI and EPI user exits for IBM CICS on Open Systems Version 2
has been added as a appendix.

Information about IBM Transaction Server for OS/2 Warp, Version 4 has been
added.

Corrections have been made to the list of related publications in the preface.

More information about security in the ECI and the EPI has been added.

A correction has been made to the description of the eci_transid field in the
ECI parameter block.

A correction has been made to the description of the Transid parameter of
CICS_EpiStartTran.

Various minor technical corrections have been made.

Small typographical errors have been corrected.


ΓòÉΓòÉΓòÉ 5. Preface ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 5.1. What this book is about ΓòÉΓòÉΓòÉ

This book is about the CICS Family programming interfaces to enable non-CICS
applications to use CICS facilities in a client-server environment. The
interfaces described are:

o External call interface (ECI)
o External presentation interface (EPI).


ΓòÉΓòÉΓòÉ 5.2. Who this book is for ΓòÉΓòÉΓòÉ

This book is for application designers and application programmers in a
client-server environment.


ΓòÉΓòÉΓòÉ 5.3. What you need to know to understand this book ΓòÉΓòÉΓòÉ

You should have a good knowledge of:

o CICS, and the CICS servers that the applications will use
o The concepts of client/server programming
o The programming language in which the applications will be written
o The programming environment in which the programs will operate.


ΓòÉΓòÉΓòÉ 5.4. Definitions ΓòÉΓòÉΓòÉ

In this book, `CICS on Open Systems' is used to refer to the following
products, subject to availability:

o CICS/6000
o CICS for AIX Version 2
o CICS for HP 9000
o CICS for Digital UNIX

`CICS on System/390' is used to refer to:

o CICS/VSE
o CICS/MVS
o CICS/ESA


ΓòÉΓòÉΓòÉ 5.5. Typographical conventions ΓòÉΓòÉΓòÉ

The presentation of names of program elements is as follows:

 1. When a program element is in lowercase, or mixed case, it is always written
    in this book in a bold face: eci_userid, CICS_EpiAddTerminal.

 2. When a program element is in uppercase, it is always written in this book
    in a normal face: ECI_ERR_LUW_TOKEN, CICS_EPI_EVENT_END_TERM.


ΓòÉΓòÉΓòÉ 5.6. Related publications ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 5.6.1. General ΓòÉΓòÉΓòÉ

o CICS Family: Library Guide, GC33-0356
o CICS Family: Interproduct Communication, SC33-0824.


ΓòÉΓòÉΓòÉ 5.6.2. Setting up client/server systems ΓòÉΓòÉΓòÉ

o IBM CICS Clients Administration, SC33-1436
o IBM CICS/6000 Version 1.2 Planning and Installation Guide, GC33-0816
o IBM CICS for AIX Version 2.1 Planning and Installation Guide, GC33-1561
o IBM CICS/6000 Version 1.2 Administration Guide, SC33-1532
o IBM CICS for AIX Version 2.1 Administration Guide, SC33-1562
o IBM CICS on Open Systems Version 1.2 Intercommunication Guide, SC33-0815
o IBM CICS on Open Systems Version 2.1 Intercommunication Guide, SC33-1564
o CICS for OS/2 Customization, SC33-0880 (Version 2), SC33-1581 (Version 3)
o CICS for OS/2 Intercommunication, SC33-0826 (Version 2), SC33-1583 (Version
  3)
o CICS for Windows NT Customization, SC33-1421
o CICS for Windows NT Intercommunication, SC33-1423
o CICS/400 Administration and Operations Guide, SC33-1387
o CICS/400 Intercommunication, SC33-1388
o CICS/ESA Resource Definition Guide, SC33-1165
o CICS/ESA Customization Guide, SC33-1166
o CICS/MVS Resource Definition (Online), SC33-0508
o CICS/MVS Customization Guide, SC33-0507
o CICS/VSE Resource Definition (Online), SC33-0708
o CICS/VSE Customization Guide, SC33-0707.


ΓòÉΓòÉΓòÉ 5.6.3. Application programming on CICS servers ΓòÉΓòÉΓòÉ

This section lists books that describe the programming environment of the CICS
servers.

o CICS for OS/2 Application Programming, SC33-0883 (Version 2), SC33-1585
  (Version 3)
o CICS for OS/2 Problem Determination, SC33-1005 (Version 2), SC33-1584
  (Version 3)
o CICS Application Programming Primer (VS COBOL II), SC33-0674
o CICS/VSE Problem Determination Guide, SC33-0716
o CICS/400 Application Programming Guide, SC33-1386
o CICS/ESA Application Programming Guide, SC33-1169
o CICS/ESA Application Programming Reference, SC33-1170
o CICS/ESA Problem Determination Guide, SC33-0678
o CICS/MVS Application Programmer's Reference, SC33-0139
o CICS/MVS Application Programming Primer, SC33-0512
o CICS for Windows NT Application Programming, SC33-1425
o CICS on Open Systems Version 1.2 Application Programming Guide, SC33-0814
o CICS on Open Systems Version 2.1 Application Programming Guide, SC33-1568
o CICS on Open Systems Version 1.2 Application Programming Reference, SC33-0886
o CICS on Open Systems Version 2.1 Application Programming Reference, SC33-1569
o CICS on Open Systems Version 1.2 Problem Determination, SC33-0818
o CICS on Open Systems Version 2.1 Problem Determination Guide, SC33-1565.


ΓòÉΓòÉΓòÉ 5.6.4. Miscellaneous ΓòÉΓòÉΓòÉ

o An Introduction to the IBM 3270 Information Display System, GA27-2739
o IBM 3270 Information Display System Data Stream Programmer's Reference,
  GA23-0059
o PL/I for OS/2 Language Reference, SC26-8003
o PL/I for OS/2 Programming Guide, SC26-8001.
o Guide to Writing DCE Applications, by John Shirley, published by O'Reilly
  Associates, Sebastopol, CA, USA, ISBN 1-56592-004-X


ΓòÉΓòÉΓòÉ 6. Introducing the external access interfaces ΓòÉΓòÉΓòÉ

This chapter introduces CICS Family Client/Server Programming, which comprises
two application programming interfaces (APIs) that provide external access to
CICS facilities:

o External call interface (ECI)
o External presentation interface (EPI)

The chapter is organized as follows:

Overview
External call interface
External presentation interface
Using the external access interfaces
ECI and EPI exits (CICS on Open Systems Version 2)


ΓòÉΓòÉΓòÉ 6.1. Overview ΓòÉΓòÉΓòÉ

The ECI and EPI allow your non-CICS applications to gain access to CICS
facilities and data.

External access interfaces in CICS client/server configurations illustrates the
use of the external interfaces by a non-CICS application in a client system.
This application is using the facilities of CICS in a server system. The CICS
client software processes the application's ECI and EPI requests, and transmits
them to the server system using an appropriate communication protocol. Although
the figure shows the client system and server system as separate workstations,
it is possible for the whole configuration to be on a single workstation.


External access interfaces in CICS client/server configurations

Some members of the CICS family provide the external interfaces to non-CICS
applications without the use of a CICS client. The non-CICS application must be
on the same workstation as the server, and is not able to communicate with
other servers. This is illustrated in Server implementation of the external
interfaces. In this case the application is using the server implementation of
the external interfaces.


Server implementation of the external interfaces

The following can be client systems that can connect to any CICS server. In
these systems an appropriate CICS client must be installed. See the CICS
Clients Administration manual.

o OS/2 - IBM CICS Client for OS/2
o DOS - IBM CICS Client for DOS
o Microsoft Windows - IBM CICS Client for Windows
o Apple Macintosh - IBM CICS Client for Macintosh

The following can be client systems that connect only to CICS on Open Systems
servers:

o AIX - IBM AIX Client for CICS/6000
o SunOS - IBM CICS Client for Sun Systems (See note below.)
o HP-UX - CICS for HP 9000
o Digital UNIX - CICS for Digital UNIX

Note:  For programming information for the SunOS environment, see the
       Installation and User's Guide for IBM CICS Client for Sun Systems.

The following server systems provide a server implementation of the external
interfaces:

o IBM CICS for OS/2
o IBM CICS for Windows NT

Any member of the CICS family can be a server, though CICS on System/390
servers support only the ECI.

The CICS on Open Systems servers are:

o IBM CICS/6000
o IBM CICS for AIX Version 2
o CICS for HP 9000
o CICS for Digital UNIX


ΓòÉΓòÉΓòÉ 6.2. External call interface ΓòÉΓòÉΓòÉ

The ECI allows a non-CICS application to call a CICS program in a CICS server.
The application can be connected to several servers at the same time, and it
can have several program calls outstanding at the same time.

The CICS program cannot perform terminal I/O, but can access and update all
other CICS resources.

External call interface illustrated shows that the same CICS program can be
called by a non-CICS application using the external call interface, or by a
CICS program using EXEC CICS LINK. Data is exchanged between the two programs
by means of a COMMAREA, in a similar way to CICS interprogram communication.


External call interface illustrated

Calls may be made synchronously or asynchronously. Synchronous calls return
control when the called program completes, and the information returned is
immediately available. Asynchronous calls return control without reference to
the completion of the called program, and the application can ask to be
notified when the information becomes available.

Calls may also be extended. That is, a single logical unit of work may cover
two or more successive calls, though only one call can be active for each
logical unit of work at any time. The application can manage many logical units
of work concurrently if it uses asynchronous calls.

The called program can update resources on its own system, it can use
distributed program link (DPL) to call CICS programs on other systems, and it
can access resources on other CICS systems by function shipping, by distributed
transaction processing (DTP), or (in the CICS/MVS and CICS/ESA environments) by
the front end programming interface (FEPI).


ΓòÉΓòÉΓòÉ 6.3. External presentation interface ΓòÉΓòÉΓòÉ

The EPI allows a non-CICS application program to be viewed as a 3270 terminal
by a CICS server system to which it is connected. External presentation
interface shows how both an EPI application and a CICS terminal can schedule
transactions in a CICS server.


External presentation interface

The application can be using the facilities of several servers at the same
time, and can act as if it were many different 3270 terminals.

The application can schedule CICS transactions, and for these transactions it
is the principal facility.

With CICS servers that support access through the EPI, other CICS transactions
running in the server can use the CICS START command to schedule transactions
that use the non-CICS application as their initiating terminal.

When a non-CICS application uses the EPI to start a transaction in a CICS
server, 3270 data streams and events are passed between the server and the
application. The application can present the contents of the terminal I/O to
its user in any manner appropriate to the application's operating environment.

Transactions can be routed to other CICS systems by standard transaction
routing. Resources on other CICS systems can be accessed by function shipping.

Note that server transactions can be existing transactions that use 3270 input
and output (with some restrictions).


ΓòÉΓòÉΓòÉ 6.4. Using the external access interfaces ΓòÉΓòÉΓòÉ

The external interfaces allow non-CICS applications to access and update CICS
resources by initiating CICS transactions or calling CICS programs. When used
in conjunction with the CICS communication facilities, they enable non-CICS
programs to access and update resources on any CICS system. This supports such
activities as:

 1. Developing graphical user interface (GUI) front ends for CICS applications,
    using Presentation Manager or other presentation systems

 2. Connecting external devices such as bar-code readers to CICS systems

 3. Allowing the integration of CICS systems and non-CICS systems.

The EPI allows you to develop GUIs, either for existing CICS systems or for new
applications. It is particularly useful for developing new GUI front ends for
existing CICS transactions, which need not be changed. The application can use
the EPI to communicate with a CICS transaction, and can exploit the
presentation facilities of the client system to communicate with the end user.

If you attach an external device such as a bar code reader, the application can
deal with device input and output, and can use the EPI to start a transaction,
perhaps one already written to deal with the kind of data that the external
device produces. The application converts the input from the external device
into a 3270 data stream to start the transaction and pass the data to it.
Output from the transaction, in the form of a 3270 data stream, is then
converted into the signals and data streams that operate the external device.

The integration of CICS and non-CICS systems usually involves passing
user-defined data between the programs of the non-CICS system and a CICS
program, and the ECI can be used for this.

In any of these cases, the choice between EPI and ECI is not always clear-cut,
because both interfaces can be used to pass data between a non-CICS application
and a CICS program. However, the mechanism is different in the two cases: 3270
data streams for EPI; application-defined formats in a COMMAREA for ECI.


ΓòÉΓòÉΓòÉ 6.5. ECI and EPI exits (CICS on Open Systems Version 2) ΓòÉΓòÉΓòÉ

The operation of the EPI and ECI can be customized by the user exits described
in ECI and EPI exits (CICS on Open Systems, Version 2).


ΓòÉΓòÉΓòÉ 7. External call interface ΓòÉΓòÉΓòÉ

This chapter provides reference information about the external call interface
(ECI).

The interface is described here in a language-independent manner, though the
names chosen for the elements of the interface-functions, parameters, data
structures, fields, constants, and so on-are similar to those provided for
programming. Language-dependent information is in Creating ECI and EPI
application programs.

On some platforms, the ECI provides facilities that are not part of CICS Family
Client/Server Programming, and these are summarized in ECI extensions that are
environment-dependent.

The chapter is organized as follows:

Overview
Program link calls
Status information calls
Reply solicitation calls
CICS_ExternalCall
ECI status block
CICS_EciListSystems.


ΓòÉΓòÉΓòÉ 7.1. Overview ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 7.1.1. ECI function ΓòÉΓòÉΓòÉ

The ECI allows a non-CICS application program to call a CICS program in a CICS
server. The non-CICS application does not issue any CICS commands itself; the
CICS commands are issued by the called program running in the server. The
called program thus appears to have been called by EXEC CICS LINK with the
COMMAREA option. An ECI application can make use of existing CICS programs that
obey the rules for distributed program link, or new CICS programs can be
written to be called by ECI applications. The called programs must follow the
rules for CICS programs called by DPL. In particular they must make no explicit
use of the EXEC CICS SYNCPOINT or EXEC CICS SYNCPOINT ROLLBACK commands.

In some circumstances it is possible for the application to be running more
than one CICS program concurrently, and these programs might be distributed
across several CICS servers.

The function provided by the ECI is packaged in two parts as follows:

CICS_ExternalCall
          Provides most of the function of the ECI. It has a single parameter,
          the ECI parameter block, in which various fields describe the
          function to be performed and the inputs and outputs. Most of the
          following sections are concerned with the use of CICS_ExternalCall.

CICS_EciListSystems
          Used to find out about available servers to which CICS_ExternalCall
          requests can be directed. It is described in CICS_EciListSystems.


ΓòÉΓòÉΓòÉ 7.1.2. Types of ECI calls ΓòÉΓòÉΓòÉ

The calls to CICS_ExternalCall are of three types:

o Program link calls
o Status information calls
o Reply solicitation calls.

The type of call to CICS_ExternalCall is controlled by the setting of the
eci_call_type parameter in the ECI parameter block.

Restrictions on call type for particular operating environments are discussed
in the descriptions of each call type.


ΓòÉΓòÉΓòÉ 7.1.2.1. Program link calls ΓòÉΓòÉΓòÉ

Program link calls cause a CICS program to be executed on a CICS server. These
calls can be:

o Synchronous - the application waits until the called program has finished.
  Returned information is immediately available.

o Asynchronous - the application gets control back without reference to the
  completion of the called program. The application can ask to be notified
  later when the information is available. It must use a reply solicitation
  call to determine the outcome of the asynchronous request.


ΓòÉΓòÉΓòÉ 7.1.2.2. Status information calls ΓòÉΓòÉΓòÉ

Status information calls retrieve status information about the type of system
on which the application is running and its status. These calls can be:

o Synchronous - the application waits until the information has been made
  available.

o Asynchronous - the application gets control back while the information is
  being retrieved. The application can ask to be notified later when the
  information is available. It must use a reply solicitation call to determine
  the outcome of the asynchronous request.


ΓòÉΓòÉΓòÉ 7.1.2.3. Reply solicitation calls ΓòÉΓòÉΓòÉ

Reply solicitation calls get information back after asynchronous program link
or asynchronous status information calls. Reply solicitation calls can be:

o General - retrieving any piece of outstanding information
o Specific -  retrieving information for a named asynchronous request.

An application that uses the asynchronous method of calling may have several
program link and status information calls outstanding at any time. The
eci_message_qualifier parameter in the ECI parameter block can be used on an
asynchronous call to provide a user-defined identifier for the call. The use of
different identifiers for different asynchronous calls within a single
application is the programmer's responsibility. When a general reply
solicitation call is made, the ECI uses the eci_message_qualifier field to
return the name of the call to which the reply belongs. When a specific reply
solicitation call is made, you must supply a value in the eci_message_qualifier
field to identify the asynchronous call about which information is begin
sought.


ΓòÉΓòÉΓòÉ 7.2. Program link calls ΓòÉΓòÉΓòÉ

Program link calls can be either synchronous or asynchronous. For asynchronous
calls, it is the responsibility of the calling application to solicit the reply
using one of the reply solicitation calls. (See Reply solicitation calls.)


ΓòÉΓòÉΓòÉ 7.2.1. Managing logical units of work ΓòÉΓòÉΓòÉ

An ECI application is often concerned with updating recoverable resources on
the server, and the application programmer needs to understand the facilities
that the ECI provides for managing logical units of work. A logical unit of
work is all the processing in the server that is needed to establish a set of
updates to recoverable resources. When the logical unit of work ends normally,
the changes will all be committed. When the logical unit of work ends
abnormally, for instance because a program abends, the changes are all backed
out. You can use the ECI to start and end logical units of work on the server.

The changes to recoverable resources in a logical unit of work might be
effected by:

o A single program link call, or
o A sequence of program link calls.

On successful return from the first of a sequence of calls for a logical unit
of work, the eci_luw_token field in the control block contains a token that
should be used for all later calls related to the same logical unit of work.
All program link calls for the same logical unit of work will be sent to the
same server.

Attention: You should be careful when extending a logical unit of work across
multiple program link calls that may span a long time (for example, over user
think time). The reason is that the logical unit of work holds various locks
and other CICS resources on the server, and this may cause delays to other
users who are waiting for those same locks and resources.

When a logical unit of work ends, the CICS server attempts to commit the
changes. The last, or only, program link call of a logical unit of work is
advised whether the attempt was successful.

Only one program link call per logical unit of work can be outstanding at any
time. (An asynchronous program link call is outstanding until a reply
solicitation call has processed the reply.)

Logical units of work in the ECI shows how you can use combinations of
eci_extend_mode, eci_program_name, and eci_luw_token parameter values to
perform tasks associated with managing logical units of work through the ECI.
In each case you must also store appropriate values in other fields for the
call type you have chosen.

Each logical unit of work ties up one CICS non-facility task for the duration
of its execution. This means that you must define enough free tasks in the CICS
server to service the maximum expected number of concurrent calls.

Asynchronous program link calls with message qualifiers and LUW tokens shows an
application program using asynchronous program calls. The program has two calls
outstanding in one server and one call in another. To keep track of its
requests, the program is using message qualifiers that it has generated itself,
and LUW tokens returned in the eci_luw_token field.


Asynchronous program link calls with message qualifiers and LUW tokens

For more details of the program link calls, you should study the descriptions
of the individual call types:

ECI_SYNC for a synchronous program link call

ECI_ASYNC for an asynchronous program link call.


ΓòÉΓòÉΓòÉ 7.2.1.1. Logical units of work in the ECI ΓòÉΓòÉΓòÉ

Call a program that is to be the only program of a logical unit of work.
          Set up the parameters as follows:

   o eci_extend_mode: ECI_NO_EXTEND
   o eci_program_name: provide it
   o eci_luw_token: zero

Call a program that is to start a new logical unit of work that is to be
extended.
          Set up the parameters as follows:

   o eci_extend_mode: ECI_EXTENDED
   o eci_program_name: provide it
   o eci_luw_token: zero

          Afterwards, save the token from eci_luw_token.

Call a program that is to continue an existing logical unit of work.
          Set up the parameters as follows:

   o eci_extend_mode: ECI_EXTENDED
   o eci_program_name: provide it
   o eci_luw_token: provide it

Call a program that is to be the last program of an existing logical unit of
work, and commit the changes.
          Set up the parameters as follows:

   o eci_extend_mode: ECI_NO_EXTEND
   o eci_program_name: provide it
   o eci_luw_token: provide it

End an existing logical unit of work, without calling another program, and
commit changes to recoverable resources.
          Set up the parameters as follows:

   o eci_extend_mode: ECI_COMMIT
   o eci_program_name: null
   o eci_luw_token: provide it

End an existing logical unit of work, without calling another program, and back
out changes to recoverable resources.
          Set up the parameters as follows:

   o eci_extend_mode: ECI_BACKOUT
   o eci_program_name: null
   o eci_luw_token: provide it


ΓòÉΓòÉΓòÉ 7.2.2. Security in the ECI ΓòÉΓòÉΓòÉ

Not all CICS servers require the client to supply a userid and password for
ECI_SYNC and ECI_ASYNC call types. Some CICS servers have configuration options
to decide whether the userid and password are required. You should consult the
publications for the appropriate server for more information.

Some client environments support the use of userids and passwords in files, so
that the userid and password need not be supplied by the non-CICS application.
Some client environments support the use of dialogs with the workstation
operator to determine userids and passwords. You should consult the
publications for the appropriate client environment for more information.

In the CICS on Open Systems environment, the operator might need DCE
authorization to use the ECI application, depending on the local configuration.
If the ECI program runs for a long time, for example longer than thirty
minutes, you must make sure that the credential lifetime and renewable lifetime
of the DCE principal are long enough to cover the maximum allowed duration of
the ECI program.

Whether userids and passwords are encrypted depends on the communications
protocol being used between client and server.


ΓòÉΓòÉΓòÉ 7.3. Status information calls ΓòÉΓòÉΓòÉ

Status information calls can be either synchronous or asynchronous. For
asynchronous calls, it is the responsibility of the calling application to
obtain the reply using a reply solicitation call (see Reply solicitation
calls).


ΓòÉΓòÉΓòÉ 7.3.1. How status information is supplied and used ΓòÉΓòÉΓòÉ

Status information is supplied in the ECI status block, which is passed across
the interface in the eci_commarea parameter.

The following status information is held in the ECI status block. For a more
detailed description, see ECI status block.

o The type of connection (whether the ECI program is locally connected to a
  CICS server, a CICS client, or nothing)

o The state of the CICS server (available, unavailable, or unknown)

o The state of the CICS client (available, not applicable, or unknown).

The status information calls allow you to perform three tasks:

o Enquire on the type of system the application is running on, and its
  connection with a given server. For this you need to provide a COMMAREA in
  which the status is returned.

o Set up a request to be notified when the status changes from some specified
  value. For this you need to provide a COMMAREA in which the specified status
  is described. When the status is different from the status specified, you are
  notified of the new status. Only asynchronous calls can be used for this
  purpose.

o Cancel a request for notification of status change. For this no COMMAREA is
  required.

Status enquiries with CICS_ExternalCall shows how you can use combinations of
eci_extend_mode, eci_commarea, eci_commarea_length, and eci_luw_token parameter
values to perform tasks associated with status enquiries. In each case you must
also store appropriate values in other fields for the call type you have
chosen.

For more details of the status information calls, you should study the
descriptions of the individual call types:

ECI_STATE_SYNC for a synchronous status information call

ECI_STATE_ASYNC for an asynchronous status information call.


ΓòÉΓòÉΓòÉ 7.3.1.1. Status enquiries with CICS_ExternalCall ΓòÉΓòÉΓòÉ

Find the current status.
          Set up the parameters as follows:

   o eci_commarea: nulls
   o eci_commarea_length: length of ECI_STATUS
   o eci_extend_mode: ECI_STATE_IMMEDIATE

          Afterwards, consult the contents of the COMMAREA to find the status.

Set up a request to find out about status change.
          Set up the parameters as follows:

   o eci_commarea: specified status
   o eci_commarea_length: length of ECI_STATUS
   o eci_extend_mode: ECI_STATE_CHANGED
   o eci_luw_token: zero

          Afterwards, save the token from eci_luw_token so that you can cancel
          the request later.

Cancel a request to find out about status change.
          Set up the parameters as follows:

   o eci_commarea: none
   o eci_commarea_length: zero
   o eci_extend_mode: ECI_STATE_CANCEL
   o eci_luw_token: provide it


ΓòÉΓòÉΓòÉ 7.4. Reply solicitation calls ΓòÉΓòÉΓòÉ

After an asynchronous program link call or asynchronous status information
call, it is the responsibility of the calling application to solicit the reply.
All calls return any outstanding reply that meets the selection criteria
specified in the call.

For more details of the reply solicitation calls, you should study the
descriptions of the individual call types:

ECI_GET_REPLY for a reply solicitation call that gets any outstanding reply for
any asynchronous call, if any reply is available.

ECI_GET_REPLY_WAIT for a reply solicitation call that gets any outstanding
reply for any asynchronous call, waiting if no replies are available.

ECI_GET_SPECIFIC_REPLY for a reply solicitation call that gets any outstanding
reply for a given asynchronous call, if any reply is available.

ECI_GET_SPECIFIC_REPLY_WAIT for a reply solicitation call that gets any
outstanding reply for a given asynchronous call, waiting if no replies are
available.


ΓòÉΓòÉΓòÉ 7.5. CICS_ExternalCall ΓòÉΓòÉΓòÉ

CICS_ExternalCall

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_ExternalCall           Γöé ECI_Parms               Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          CICS_ExternalCall gives access to the program link calls, status
          information calls, and reply solicitation calls described above. The
          function performed is controlled by the eci_call_type field in the
          ECI parameter block.

 Parameters

          ECI_Parms
                    A pointer to the ECI parameter block. The parameter block
                    must be set to nulls before use. The parameter block fields
                    that are used as input and output are described in detail
                    for each call type in the following sections. A brief
                    summary of the fields is given next:

             eci_call_type
                       An integer field defining the type of call being made.
                       For details of the functions provided, see Types of ECI
                       calls.

             eci_program_name
                       The name of a program to be called.

             eci_userid
                       Userid for security checking.

             eci_password
                       Password for security checking.

             eci_transid
                       A transaction identifier.

             eci_abend_code
                       Abend code for a failed program.

             eci_commarea
                       A COMMAREA for use by a called program, or for returned
                       status information.

             eci_commarea_length
                       The length of the COMMAREA.

             eci_timeout
                       This field is provided for migration of existing ECI
                       applications, and should normally be set to zero.

             eci_sys_return_code
                       A return code giving more information about an
                       unexpected error.

             eci_extend_mode
                       A field that qualifies the function to be performed in
                       various ways.

             eci_message_qualifier
                       A user-provided reference to an asynchronous call.

             eci_luw_token
                       An identifier for a logical unit of work.

             eci_sysid
                       Reserved for future use, leave null.

             eci_version
                       The version of the ECI for which the application is
                       coded. In the CICS on Open Systems environment, only
                       ECI_VERSION_1 may be specified. In other environments,
                       you may use the values ECI_VERSION_1 or ECI_VERSION_1A.
                       Facilities available only in version 1A are noted where
                       they occur. The use of the value ECI_VERSION_0 is
                       confined to programs migrated from previous versions of
                       the ECI.

             eci_system_name
                       The name of a CICS server.

             eci_callback
                       A pointer to a callback routine for an asynchronous
                       request.

             eci_userid2
                       Userid for security checking.

             eci_password2
                       Password for security checking.

             eci_tpn
                       A transaction identifier for a mirror transaction. This
                       field is available only when eci_version has the value
                       ECI_VERSION_1A.

 Return codes

          In addition to the return codes described for each call type in the
          following sections, the following return codes are possible.

          ECI_ERR_INVALID_CALL_TYPE
                    The call type was not one of the valid call types.

          ECI_ERR_CALL_FROM_CALLBACK
                    The call was made from a callback routine.

          ECI_ERR_SYSTEM_ERROR
                    An internal system error occurred. The error might have
                    been in the client or in the server. The programmer should
                    save the information returned in the eci_sys_return_code
                    field, as this will help service personnel to diagnose the
                    error.

          ECI_ERR_INVALID_VERSION
                    The value supplied for eci_version was invalid.

          ECI_ERR_REQUEST_TIMEOUT
                    The value in the eci_timeout field of the ECI parameter
                    block is negative.

          In some implementations, some of the return codes documented here and
          for each call type will never be returned.


ΓòÉΓòÉΓòÉ 7.5.1. ECI_SYNC call type ΓòÉΓòÉΓòÉ

ECI_SYNC call type

 Environment

          The ECI_SYNC call type is available in all environments.

 Purpose

          The ECI_SYNC call type provides a synchronous program link call to
          start, continue, or end a logical unit of work. The calling
          application does not get control back until the called CICS program
          has run to completion.

 ECI parameter block fields

          The ECI parameter block should be set to nulls before setting the
          input parameter fields.

          eci_call_type
                    Required input parameter.

                    Must be set to ECI_SYNC.

          eci_program_name
                    Input parameter, required except when eci_extend_mode is
                    ECI_COMMIT or ECI_BACKOUT. (See Logical units of work in
                    the ECI.)

                    An 8-character field containing the name of the program to
                    be called. Unused characters should be padded with spaces.
                    This field is transmitted to the server without conversion
                    to uppercase.

          eci_userid
                    Required input parameter.

                    An 8-character field containing a userid. Unused characters
                    should be padded with spaces. On CICS on Open Systems
                    clients, this field is transmitted to the server without
                    conversion to uppercase. In other environments, you should
                    consult the documentation for the client and the server to
                    check whether this field is converted to upper case before
                    being transmitted to the server. (If a userid or password
                    longer than 8 characters is required, eci_version must not
                    be ECI_VERSION_0; and eci_userid and eci_password must be
                    set to nulls, and the fields eci_userid2 and eci_password2
                    used instead.)

                    If a userid is supplied, then the server uses the userid
                    and any supplied password to authenticate the user. The
                    supplied userid and password are used in subsequent
                    security checking in the server.

          eci_password
                    Required input parameter.

                    An 8-character field containing a password. Unused
                    characters should be padded with spaces. On CICS on Open
                    Systems clients, this field is transmitted to the server
                    without conversion to uppercase. In other environments, you
                    should consult the documentation for the client and the
                    server to check whether this field is converted to upper
                    case before being transmitted to the server. (If a userid
                    or password longer than 8 characters is required, this
                    field and eci_userid must be set to nulls, and the fields
                    eci_userid2 and eci_password2 used instead.)

          eci_transid
                    Optional input parameter

                    A 4-character field optionally containing the ID of a CICS
                    transaction. Unused characters should be padded with
                    spaces. This field is transmitted to the server without
                    conversion to uppercase. The use of this parameter depends
                    on the server to which the request is directed.

             o For a CICS on Open Systems server, this is the name of the
               transaction that will be used to service the request. The name
               you choose must be defined as a transaction name on the server,
               and must be associated with the program DFHMIRS.

             o For other CICS servers, this is the name of the transaction
               under which the called program will run. This name is available
               to the called program for querying the transaction ID; use it if
               the CICS program issues a distributed program link, and if the
               transaction ID under which the program runs is important. Some
               servers use the transaction ID to determine security and
               performance attributes for the called program. You are
               recommended to use this parameter to control the processing of
               your called programs.

                    If the ECI request is extended (see the description of
                    eci_extend_mode), all calls in the same logical unit of
                    work must use the same value for eci_transid.

                    If the field is all nulls, the default server transaction
                    ID is used.

          eci_abend_code
                    Output parameter.

                    A 4-character field in which a CICS abend code is returned
                    if the transaction that executes the called program abends.
                    Unused characters are padded with spaces.

          eci_commarea
                    Optional input parameter.

                    A pointer to the data to be passed to the called CICS
                    program as its COMMAREA. The COMMAREA will be used by the
                    called program to return information to the application.

                    If no COMMAREA is required, supply a null pointer and set
                    the length (specified in eci_commarea_length) to zero.

                    If the code page of the application is different from the
                    code page of the server, data conversion must be performed
                    at the server. To do this, you need to make use of
                    CICS-supplied resource conversion capabilities, such as the
                    DFHCNV macro definitions.

          eci_commarea_length
                    Optional input parameter.

                    The length of the COMMAREA in bytes. This value may not
                    exceed 32500. (Some client-server combinations may allow
                    larger COMMAREAs, but this is not guaranteed to work as
                    part of CICS Family Client/Server Programming.)

                    If no COMMAREA is required, set this field to zero and
                    supply a null pointer in eci_commarea.

          eci_sys_return_code
                    Output parameter.

                    An integer field containing additional information when the
                    return code is ECI_ERR_SYSTEM_ERROR. The meaning of this
                    information depends on the software and hardware platform.
                    You should save this information, as it will help service
                    personnel to diagnose the error.

          eci_extend_mode
                    Required input parameter.

                    An integer field determining whether a logical unit of work
                    is terminated at the end of this call. (See Logical units
                    of work in the ECI.)

                    The values for this field (shown by their symbolic names)
                    are as follows:

             ECI_NO_EXTEND

                 1. If the input eci_luw_token field is zero, this is the only
                    call for a logical unit of work.

                 2. If the input eci_luw_token field is not zero, this is the
                    last call for the specified logical unit of work.

                  In either case, changes to recoverable resources are
                  committed by a CICS end-of-task syncpoint, and the logical
                  unit of work ends.

             ECI_EXTENDED

                 1. If the input eci_luw_token field is zero, this is the first
                    call for a logical unit of work that is to be continued.

                 2. If the input eci_luw_token field is not zero, this call is
                    intended to continue the specified logical unit of work.

                  In either case the logical unit of work continues after the
                  called program completes successfully, and changes to
                  recoverable resources remain uncommitted.

             ECI_COMMIT
                  Terminate the current logical unit of work, identified by the
                  input eci_luw_token field, and commit all changes made to
                  recoverable resources.

             ECI_BACKOUT
                  Terminate the logical unit of work identified by the input
                  eci_luw_token field, and back out all changes made to
                  recoverable resources.

          eci_luw_token
                    Required input and output parameter.

                    An integer field used for identifying the logical unit of
                    work to which a call belongs. It must be set to zero at the
                    start of a logical unit of work (regardless of whether the
                    logical unit of work is going to be extended). If the
                    logical unit of work is to be extended, the ECI updates
                    eci_luw_token with a valid value on the first call of the
                    logical unit of work, and this value should be used as
                    input to all later calls related to the same logical unit
                    of work. (See Logical units of work in the ECI.)

                    If the return code is not ECI_NO_ERROR, and the call was
                    continuing or ending an existing logical unit of work, this
                    field is used as output to report the condition of the
                    logical unit of work. If it is set to zero, the logical
                    unit of work has ended, and its updates have been backed
                    out. If it is nonzero, it is the same as the input value,
                    the logical unit of work is continuing, and its updates are
                    still pending.

          eci_sysid
                    Required input parameter.

                    Reserved for future use, but this field should be
                    initialized with nulls before the start of each logical
                    unit of work.

          eci_version
                    Required input parameter.

                    The version of the ECI for which the application is coded.
                    In the CICS on Open Systems environment, only ECI_VERSION_1
                    may be specified. In other environments, you may use the
                    values ECI_VERSION_1 or ECI_VERSION_1A. All the facilities
                    of version 1 are available in version 1A. Facilities
                    available only in version 1A are noted where they occur.
                    (ECI_VERSION_0 is provided to allow applications written
                    for previous versions of the ECI to continue to execute,
                    but many of the facilities of CICS Client/Server
                    Programming are not available if eci_version has this
                    value.)

          eci_system_name
                    Optional input parameter.

                    An 8-character field that specifies the name of the server
                    to which the ECI request is to be directed. Unused
                    characters should be padded with spaces. If supplied, it
                    should be one of the server names returned by
                    CICS_EciListSystems. The value may be supplied whenever
                    eci_luw_token is set to zero. (If it is supplied when
                    eci_luw_token is not zero, it is ignored, because the
                    server was established at the start of the logical unit of
                    work.)

                    If the field is set to nulls, then a server, currently the
                    default server, is selected; the name of the chosen server
                    is returned in this field, and must be used in subsequent
                    related ECI requests. If ECI requests made in different
                    logical units of work must be directed to the same server,
                    then eci_system_name must identify that server by name.

          eci_userid2
                    Optional input parameter.

                    If the eci_userid field is set to nulls, then the
                    eci_userid2 field specifies the userid (if any) to be used
                    at the server for any authority validation. The userid can
                    be up to 16 characters. eci_version must not be
                    ECI_VERSION_0.

                    See the description of the eci_userid field for information
                    about how the userid is used.

          eci_password2
                    Optional input parameter.

                    If the eci_password field is set to nulls, the
                    eci_password2 field specifies the password (if any) to be
                    used at the server for any authority validation. The
                    password can be up to 16 characters. eci_version must not
                    be ECI_VERSION_0.

                    See the description of the eci_password field for
                    information about how the password is used.

          eci_tpn
                    Optional input parameter. Available only if the value of
                    eci_version is ECI_VERSION_1A.

                    A 4-character field that specifies the transaction ID of
                    the transaction that will be used in the server to process
                    the ECI request. This transaction must be defined in the
                    server as a CICS mirror transaction. If the field is not
                    set, the default mirror transaction CAMI is used.

                    If the ECI request is extended (see the description of
                    eci_extend_mode), you need specify this only for the first
                    request. If you specify a value for subsequent requests, it
                    is ignored, and the value specified for the first request
                    is reused.

 Return codes

          See also the general list of return codes for CICS_ExternalCall in
          CICS_ExternalCall.

          ECI_NO_ERROR
                    The call completed successfully.

          ECI_ERR_INVALID_DATA_LENGTH
                    The value in eci_commarea_length field is outside the valid
                    range, or is inconsistent with the value in eci_commarea,
                    being zero for a non-null eci_commarea pointer, or non-zero
                    for a null eci_commarea pointer.

          ECI_ERR_INVALID_EXTEND_MODE
                    The value in eci_extend_mode field is not valid.

          ECI_ERR_NO_CICS
                    The client is unavailable, or the server implementation is
                    unavailable, or a logical unit of work was to be begun, but
                    the CICS server specified in eci_system_name is not
                    available. No resources have been updated.

          ECI_ERR_CICS_DIED
                    A logical unit of work was to be begun or continued, but
                    the CICS server was no longer available. If eci_extend_mode
                    was ECI_EXTENDED, the changes are backed out, and the
                    logical unit of work ends. If eci_extend_mode was
                    ECI_NO_EXTEND, ECI_COMMIT, or ECI_BACKOUT, the application
                    cannot determine whether the changes have been committed or
                    backed out, and must log this condition to aid future
                    manual recovery.

          ECI_ERR_TRANSACTION_ABEND
                    The CICS transaction that executed the requested program
                    abended. The abend code will be found in eci_abend_code.
                    For information about abend codes and their meaning, you
                    should consult the documentation for the server system to
                    which the request was directed.

          ECI_ERR_LUW_TOKEN
                    The value supplied in  eci_luw_token is invalid.

          ECI_ERR_ALREADY_ACTIVE
                    An attempt was made to continue an existing logical unit of
                    work, but there was an outstanding asynchronous call for
                    the same logical unit of work.

          ECI_ERR_RESOURCE_SHORTAGE
                    The server implementation or the client did not have enough
                    resources to complete the request.

          ECI_ERR_NO_SESSIONS
                    A new logical unit of work was being created, but the
                    application already has as many outstanding logical units
                    of work as the configuration will support.

          ECI_ERR_INVALID_DATA_AREA
                    Either the pointer to the ECI parameter block is invalid,
                    or the pointer supplied in eci_commarea is invalid.

          ECI_ERR_ROLLEDBACK
                    An attempt was made to commit a logical unit of work, but
                    the server was unable to commit the changes, and backed
                    them out instead.

          ECI_ERR_UNKNOWN_SERVER
                    The requested server could not be located. Only servers
                    returned by CICS_EciListSystems are acceptable.

          ECI_ERR_INVALID_TRANSID
                    A logical unit of work was being extended, but the value
                    supplied in eci_transid differed from the value used when
                    the logical unit of work was started.

          ECI_ERR_MAX_SESSIONS
                    There were not enough communication resources to satisfy
                    the request. You should consult the documentation for your
                    client or server to see how to control communication
                    resources.

          ECI_ERR_MAX_SYSTEMS
                    You attempted to start requests to more servers than your
                    configuration allows. You should consult the documentation
                    for your client or server to see how to control the number
                    of servers you can use.

          ECI_ERR_SECURITY_ERROR
                    You did not supply a valid combination of userid and
                    password, though the server expects it.


ΓòÉΓòÉΓòÉ 7.5.2. ECI_ASYNC call type ΓòÉΓòÉΓòÉ

ECI_ASYNC call type

 Environment

          The ECI_ASYNC call type is available in all environments except DOS.

 Purpose

          The ECI_ASYNC call type provides an asynchronous program link call to
          start, continue, or end a logical unit of work. The calling
          application gets control back when the ECI has accepted the request.
          At this point the parameters have been validated; however, the
          request might still be queued for later processing.

          If no callback routine is provided, the application must use a reply
          solicitation call to determine that the request has ended and what
          the outcome was.

          If a callback routine is provided, the callback routine eci_callback
          is invoked when a response is available.

          Note:  Some compilers do not support the use of callback routines.
                 Consult your compiler documentation for more information.

          When the callback routine is called, it is passed a single
          parameter-the value specified in eci_message_qualifier. Use of this
          parameter enables the callback routine to identify the asynchronous
          call that is completing. Note the following guidelines on the use of
          the callback routine:

           1. The minimum possible processing should be performed within the
              callback routine.

           2. ECI functions cannot be invoked from within the callback routine.

           3. The callback routine should indicate to the main body of the
              application that the reply is available using an appropriate
              technique for the operating system upon which the ECI application
              is executing. For example, in a multithreaded environment like
              OS/2, the callback routine might post a semaphore to signal
              another thread that an event has occurred. In a Presentation
              Manager environment, it might post a message to a window to
              indicate to the window procedure that an event has occurred.
              Other actions would be appropriate for other environments.

           4. In a CICS on Open Systems environment, only thread-safe
              facilities should be used.

           5. The application, not the callback routine, must use a reply
              solicitation call to receive the actual response.

 ECI parameter block fields

          The ECI parameter block should be set to nulls before setting the
          input parameter fields.

          eci_call_type
                    Required input parameter.

                    Must be set to ECI_ASYNC.

          eci_program_name
                    Input only, required parameter except when eci_extend_mode
                    is ECI_COMMIT or ECI_BACKOUT. (See Logical units of work in
                    the ECI.)

                    An 8-character field containing the name of the program to
                    be called. Unused characters should be padded with spaces.
                    This field is transmitted to the server without conversion
                    to uppercase.

          eci_userid
                    Required input parameter.

                    An 8-character field containing a userid. Unused characters
                    should be padded with spaces. On CICS on Open Systems
                    clients, this field is transmitted to the server without
                    conversion to uppercase. In other environments, you should
                    consult the documentation for the client and the server to
                    check whether this field is converted to upper case before
                    being transmitted to the server. (If a userid or password
                    longer than 8 characters is required, eci_version must not
                    be ECI_VERSION_0; and eci_userid and eci_password must be
                    set to nulls, and the fields eci_userid2 and eci_password2
                    used instead.)

                    If a userid is supplied, then the userid and any supplied
                    password will be used by the server to validate the
                    authority of the user to execute the ECI request. The form
                    of this validation is defined by the server.

          eci_password
                    Required input parameter.

                    An 8-character field containing a password. Unused
                    characters should be padded with spaces. On CICS on Open
                    Systems clients, this field is transmitted to the server
                    without conversion to uppercase. In other environments, you
                    should consult the documentation for the client and the
                    server to check whether this field is converted to upper
                    case before being transmitted to the server. (If a userid
                    or password longer than 8 characters is required, this
                    field and eci_userid must be set to nulls, and the fields
                    eci_userid2 and eci_password2 used instead.)

          eci_transid
                    Optional input parameter.

                    A 4-character field optionally containing a CICS
                    transaction ID. Unused characters should be padded with
                    spaces. This field is transmitted to the server without
                    conversion to uppercase. The use of this parameter depends
                    on the server to which the request is directed.

             o For a CICS on Open Systems server, this is the name of the
               transaction that will be used to service the request. The name
               you choose must be defined as a transaction name on the server,
               and must be associated with the program DFHMIRS.

             o For other CICS servers, this is the name of the transaction
               under which the called program will run. This name is available
               to the called program for querying the transaction ID; use it if
               the CICS program issues a distributed program link, and if the
               transaction ID under which the program runs is important. Some
               servers use the transaction ID to determine security and
               performance attributes for the called program. You are
               recommended to use this parameter to control the processing of
               your called programs.

                    If the ECI request is extended (see the description of
                    eci_extend_mode), all calls in the same logical unit of
                    work must use the same value for eci_transid.

                    If the field is all nulls, the default server transaction
                    ID is used.

          eci_commarea
                    Required input parameter.

                    A pointer to the data to be passed to the called CICS
                    program as its COMMAREA.

                    If no COMMAREA is required, supply a null pointer and set
                    the length (specified in eci_commarea_length) to zero.

                    If the code page of the application is different from the
                    code page of the server, data conversion must be performed
                    at the server. To do this, you need to make use of
                    CICS-supplied resource conversion capabilities, such as the
                    DFHCNV macro definitions.

          eci_commarea_length
                    Required input parameter.

                    The length of the COMMAREA in bytes. This value may not
                    exceed 32500. (Some client-server combinations may allow
                    larger COMMAREAs, but this is not guaranteed to work as
                    part of CICS Family Client/Server Programming.)

                    If no COMMAREA is required, set this field to zero and
                    supply a null pointer in eci_commarea.

          eci_sys_return_code
                    Output parameter.

                    An integer field containing additional information when the
                    return code is ECI_ERR_SYSTEM_ERROR. The meaning of this
                    information depends on the software and hardware platform.
                    You should save this information, as it will help service
                    personnel to diagnose the error.

          eci_extend_mode
                    Required input parameter.

                    An integer field determining whether a logical unit of work
                    is terminated at the end of this call. (See Logical units
                    of work in the ECI.)

                    Values (shown by their symbolic names) for this field are
                    as follows:

             ECI_NO_EXTEND

                 1. If the input eci_luw_token field is zero, this is the only
                    call for a logical unit of work.

                 2. If the input eci_luw_token field is not zero, this is the
                    last call for the specified logical unit of work.

                  In either case, changes to recoverable resources are
                  committed by a CICS end-of-task syncpoint, and the logical
                  unit of work ends.

             ECI_EXTENDED

                 1. If the input eci_luw_token field is zero, this is the first
                    call for a logical unit of work that is to be continued.

                 2. If the input eci_luw_token field is not zero, this call is
                    intended to continue the specified logical unit of work.

                  In either case the logical unit of work continues after the
                  called program completes, and changes to recoverable
                  resources remain uncommitted.

             ECI_COMMIT
                  Terminate the current logical unit of work, identified by the
                  input eci_luw_token field, and commit all changes made to
                  recoverable resources.

             ECI_BACKOUT
                  Terminate the logical unit of work identified by the input
                  eci_luw_token field, and back out all changes made to
                  recoverable resources.

          eci_message_qualifier
                    Optional input parameter.

                    An integer field allowing the application to identify each
                    asynchronous call if it is making more than one. If a
                    callback routine is specified, the value in this field is
                    returned to the callback routine during the notification
                    process.

          eci_luw_token
                    Required input and output parameter.

                    An integer field used for identifying the logical unit of
                    work to which a call belongs. It must be set to zero at the
                    start of a logical unit of work (regardless of whether the
                    logical unit of work is going to be extended), and the ECI
                    updates it with a valid value on the first or only call of
                    the logical unit of work. If the logical unit of work is to
                    be extended, this value should be used as input to all
                    later calls related to the same logical unit of work. See
                    Logical units of work in the ECI.

                    If the return code is not ECI_NO_ERROR, and the call was
                    continuing or ending an existing logical unit of work, this
                    field is used as output to report the condition of the
                    logical unit of work. If it is set to zero, the logical
                    unit of work has ended, and its updates have been backed
                    out. If it is nonzero, it is the same as the input value,
                    the logical unit of work is continuing, and its updates are
                    still pending.

          eci_sysid
                    Required input parameter.

                    Reserved for future use, but this field should be
                    initialized with nulls before the start of each logical
                    unit of work.

          eci_version
                    Required input parameter.

                    The version of the ECI for which the application is coded.
                    In the CICS on Open Systems environment, only ECI_VERSION_1
                    may be specified. In other environments, you may use the
                    values ECI_VERSION_1 or ECI_VERSION_1A. All the facilities
                    of version 1 are available in version 1A. Facilities
                    available only in version 1A are noted where they occur.
                    (ECI_VERSION_0 is provided to allow applications written
                    for previous versions of the ECI to continue to execute,
                    but many of the facilities of CICS Client/Server
                    Programming are not available if eci_version has this
                    value.)

          eci_system_name
                    Optional input parameter.

                    An 8-character field that specifies the name of the server
                    to which the ECI request is to be directed. Unused
                    characters should be padded with spaces. The value may be
                    supplied whenever eci_luw_token is set to zero. (If it is
                    supplied when eci_luw_token is not zero, it is ignored,
                    because the server was established at the start of the
                    logical unit of work.)

                    If the field is set to nulls, then a server, currently the
                    default server, is selected. You can obtain the name of the
                    chosen server from the eci_system_name field of the reply
                    solicitation call you use to get the result of this
                    asynchronous request. (If later ECI requests made in
                    different logical units of work must be directed to the
                    same server as this request, then eci_system_name in those
                    requests must identify that server by name.)

          eci_callback
                    Optional input parameter.

                    A pointer to the routine to be called when the asynchronous
                    request completes. (The callback routine will be called
                    only if the return code is ECI_NO_ERROR, and the pointer is
                    not null.)

          eci_userid2
                    Optional input parameter.

                    If the eci_userid field is set to nulls, then the
                    eci_userid2 field specifies the userid (if any) to be used
                    at the server for any authority validation. The userid can
                    be up to 16 characters. eci_version must not be
                    ECI_VERSION_0.

                    See the description of the eci_userid field for information
                    about how the userid is used.

          eci_password2
                    Optional input parameter.

                    If the eci_password field is set to nulls, the
                    eci_password2 field specifies the password (if any) to be
                    used at the server for any authority validation. The
                    password can be up to 16 characters. eci_version must not
                    be ECI_VERSION_0.

                    See the description of the eci_password field for
                    information about how the password is used.

          eci_tpn
                    Optional input parameter. Available only if the value of
                    eci_version is ECI_VERSION_1A.

                    A 4-character field that specifies the transaction ID of
                    the transaction that will be used in the server to process
                    the ECI request. This transaction must be defined in the
                    server as a CICS mirror transaction. If the field is not
                    set, the default mirror transaction CAMI is used.

                    If the ECI request is extended (see the description of
                    eci_extend_mode), you need specify this only for the first
                    request. If you specify a value for subsequent requests, it
                    is ignored, and the value specified for the first request
                    is reused.

 Return codes

          See also the general list of return codes for CICS_ExternalCall in
          CICS_ExternalCall.

          If the return code is not ECI_NO_ERROR, the callback routine will not
          be called, and there will be no asynchronous reply for this request.

          ECI_NO_ERROR
                    The call to the ECI completed successfully. No errors have
                    yet been detected. The callback routine will be called when
                    the request completes.

          ECI_ERR_INVALID_DATA_LENGTH
                    The value in eci_commarea_length field is outside the valid
                    range, or is inconsistent with the value in eci_commarea,
                    being zero for a non-null eci_commarea pointer, or non-zero
                    for a null eci_commarea pointer.

          ECI_ERR_INVALID_EXTEND_MODE
                    The value in eci_extend_mode field is not valid.

          ECI_ERR_NO_CICS
                    Either the client or the server implementation is not
                    available.

          ECI_ERR_LUW_TOKEN
                    The value supplied in  eci_luw_token is invalid.

          ECI_ERR_THREAD_CREATE_ERROR
                    The server implementation or the client failed to create a
                    thread to process the request.

          ECI_ERR_ALREADY_ACTIVE
                    An attempt was made to continue an existing logical unit of
                    work, but there was an outstanding asynchronous call for
                    the same logical unit of work.

          ECI_ERR_RESOURCE_SHORTAGE
                    The server implementation or the client did not have enough
                    resources to complete the request.

          ECI_ERR_NO_SESSIONS
                    A new logical unit of work was being created, but the
                    application already has as many outstanding logical units
                    of work as the configuration will support.

          ECI_ERR_INVALID_DATA_AREA
                    Either the pointer to the ECI parameter block is invalid,
                    or the pointer supplied in eci_commarea is invalid.

          ECI_ERR_INVALID_TRANSID
                    A logical unit of work was being extended, but the value
                    supplied in eci_transid differed from the value used when
                    the logical unit of work was started.


ΓòÉΓòÉΓòÉ 7.5.3. ECI_STATE_SYNC call type ΓòÉΓòÉΓòÉ

ECI_STATE_SYNC call type

 Environment

          The ECI_STATE_SYNC call type is available in all environments.

 Purpose

          The ECI_STATE_SYNC call type provides a synchronous status
          information call.

 ECI parameter block fields

          The ECI parameter block should be set to nulls before setting the
          input parameter fields.

          eci_call_type
                    Required input parameter.

                    Must be set to ECI_STATE_SYNC.

          eci_commarea
                    Input parameter, required except when eci_extend_mode has
                    the value ECI_STATE_CANCEL.

                    A pointer to the area of storage where the application
                    receives the returned COMMAREA containing status
                    information (see Status information calls and ECI status
                    block for more details).

                    If eci_extend_mode has the value ECI_STATE_CANCEL, supply a
                    null pointer and set the length (specified in
                    eci_commarea_length) to zero.

          eci_commarea_length
                    Required input and output parameter, except when
                    eci_extend_mode has the value ECI_STATE_CANCEL.

                    The length of the COMMAREA in bytes, which must be the
                    length of the ECI_STATUS structure that gives the layout of
                    the status information COMMAREA (see Status information
                    calls and ECI status block for more details).

                    If no COMMAREA is required, set this field to zero and
                    supply a null pointer in eci_commarea.

          eci_sys_return_code
                    Output parameter.

                    An integer field containing additional information when the
                    return code is ECI_ERR_SYSTEM_ERROR. The meaning of this
                    information depends on the software and hardware platform.
                    You should save this information, as it will help service
                    personnel to diagnose the error.

          eci_extend_mode
                    Required input parameter.

                    An integer field further qualifying the call type. (See
                    Status enquiries with CICS_ExternalCall.) The values for
                    this field (shown by their symbolic names) are as follows:

             ECI_STATE_IMMEDIATE
                  Force a status reply to be sent immediately it is available.
                  The layout of the returned COMMAREA is defined in the
                  ECI_STATUS structure (see Status information calls and ECI
                  status block).

             ECI_STATE_CHANGED
                  Force a status reply to be sent only when the status changes.
                  The supplied COMMAREA must contain the status as perceived by
                  the application. A reply is sent only when there is a change
                  from the status that the application supplied. The layout of
                  the COMMAREA is defined in the ECI_STATUS structure (see
                  Status information calls and ECI status block for more
                  details). The eci_luw_token field that is returned on the
                  immediate response provides a token to identify the request.

             ECI_STATE_CANCEL
                  Cancel an ECI_STATE_CHANGED type of operation. No COMMAREA is
                  required for this request. The eci_luw_token field must
                  contain the token that was received during the
                  ECI_STATE_CHANGED call.

          eci_luw_token
                    Optional input and output parameter.

                    When a deferred status request is being set up
                    (eci_extend_mode set to ECI_STATE_CHANGED), the token
                    identifying the request is returned in the eci_luw_token
                    field.

                    When a deferred status request is being cancelled
                    (eci_extend_mode set to ECI_STATE_CANCEL), the
                    eci_luw_token field must contain the token that was
                    received during the ECI_STATE_CHANGED call.

                    This field is not used when other values of eci_extend_mode
                    are specified.

          eci_sysid
                    Required input parameter.

                    Reserved for future use, but this field should be
                    initialized with nulls before the start of each logical
                    unit of work.

          eci_version
                    Required input parameter.

                    The version of the ECI for which the application is coded.
                    In the CICS on Open Systems environment, only ECI_VERSION_1
                    may be specified. In other environments, you may use the
                    values ECI_VERSION_1 or ECI_VERSION_1A. All the facilities
                    of version 1 are available in version 1A. Facilities
                    available only in version 1A are noted where they occur.
                    (ECI_VERSION_0 is provided to allow applications written
                    for previous versions of the ECI to continue to execute,
                    but many of the facilities of CICS Client/Server
                    Programming are not available if eci_version has this
                    value.)

          eci_system_name
                    Optional input parameter.

                    An 8-character field that specifies the name of the server
                    for which status information is required. Unused characters
                    should be padded with spaces. If supplied, it should be one
                    of the server names returned by CICS_EciListSystems. The
                    value may be supplied whenever eci_luw_token is set to
                    zero.

                    If the field is set to nulls, then a server, currently the
                    default server, is selected; the name of the chosen server
                    is returned in this

 Return codes

          See also the general list of return codes for CICS_ExternalCall in
          CICS_ExternalCall.

          ECI_NO_ERROR
                    The call completed successfully.

          ECI_ERR_INVALID_DATA_LENGTH
                    The value in eci_commarea_length field is outside the valid
                    range, or is inconsistent with the value in eci_commarea,
                    being zero for a non-null eci_commarea pointer, or non-zero
                    for a null eci_commarea pointer.

          ECI_ERR_INVALID_EXTEND_MODE
                    The value in eci_extend_mode field is not valid.

          ECI_ERR_LUW_TOKEN
                    The value supplied in  eci_luw_token is invalid.

          ECI_ERR_INVALID_DATA_AREA
                    Either the pointer to the ECI parameter block is invalid,
                    or the pointer supplied in eci_commarea is invalid.

          ECI_ERR_UNKNOWN_SERVER
                    The requested server could not be located. Only servers
                    returned by CICS_EciListSystems are acceptable.


ΓòÉΓòÉΓòÉ 7.5.4. ECI_STATE_ASYNC call type ΓòÉΓòÉΓòÉ

ECI_STATE_ASYNC call type

 Environment

          The ECI_STATE_ASYNC call type is available in all environments except
          DOS.

 Purpose

          The ECI_STATE_ASYNC call type provides an asynchronous status
          information call. The calling application gets control back when the
          ECI accepts the request. At this point the parameters have been
          validated; however, the request might still be queued for later
          processing.

          If no callback routine is provided, the application must use a reply
          solicitation call to determine that the request has ended and what
          the outcome was.

          If a callback routine is provided, the callback routine eci_callback
          is invoked when a response is available.

          Note:  Some compilers do not support the use of callback routines.
                 Consult your compiler documentation for more information.

          When the callback routine is called, it is passed a single
          parameter-the value specified in eci_message_qualifier. Use of this
          parameter enables the callback routine to identify the asynchronous
          call that is completing. Note the following guidelines on the use of
          the callback routine:

           1. The minimum possible processing should be performed within the
              callback routine.

           2. ECI functions cannot be invoked from within the callback routine.

           3. The callback routine should indicate to the main body of the
              application that the reply is available using an appropriate
              technique for the operating system upon which the ECI application
              is executing. For example, in a multithreaded environment like
              OS/2, the callback routine might post a semaphore to signal
              another thread that an event has occurred. In a Presentation
              Manager environment, it might post a message to a window to
              indicate to the window procedure that an event has occurred.
              Other actions would be appropriate for other environments.

           4. In a CICS on Open Systems environment, only thread-safe
              facilities should be used.

           5. The application, not the callback routine, must use a reply
              solicitation call to receive the actual response.

 ECI parameter block fields

          The ECI parameter block should be set to nulls before setting the
          input parameter fields.

          eci_call_type
                    Required input parameter.

                    Must be set to ECI_STATE_ASYNC.

          eci_commarea
                    Input parameter, required except when eci_extend_mode has
                    the value ECI_STATE_CANCEL.

                    A pointer to the area of storage where the application
                    receives the returned COMMAREA containing status
                    information (see Status information calls and ECI status
                    block for more details).

                    If eci_extend_mode has the value ECI_STATE_CANCEL, supply a
                    null pointer and set the length (specified in
                    eci_commarea_length) to zero.

          eci_commarea_length
                    Required input parameter, except when eci_extend_mode has
                    the value ECI_STATE_CANCEL.

                    The length of the COMMAREA in bytes, which must be the
                    length of the ECI_STATUS structure that gives the layout of
                    the status information COMMAREA (see Status information
                    calls and ECI status block for more details).

                    If no COMMAREA is required, set this field to zero and
                    supply a null pointer in eci_commarea.

          eci_sys_return_code
                    Output parameter.

                    An integer field containing additional information when the
                    return code is ECI_ERR_SYSTEM_ERROR. The meaning of this
                    information depends on the software and hardware platform.
                    You should save this information, as it will help service
                    personnel to diagnose the error.

          eci_extend_mode
                    Required input parameter.

                    An integer field further qualifying the call type. (See
                    Status enquiries with CICS_ExternalCall.) The values for
                    this field (shown by their symbolic names) are as follows:

             ECI_STATE_IMMEDIATE
                  Force a status reply to be sent immediately it is available.
                  The layout of the returned COMMAREA is defined in the
                  ECI_STATUS structure (see Status information calls and ECI
                  status block

             ECI_STATE_CHANGED
                  Force a status reply to be sent only when the status changes.
                  The supplied COMMAREA must contain the status as perceived by
                  the application. A reply is sent only when there is a change
                  from the status that the application supplied. The layout of
                  the COMMAREA is defined in the ECI_STATUS structure (see
                  Status information calls and ECI status block for more
                  details). The eci_luw_token field that is returned on the
                  immediate response identifies the logical unit of work to
                  which this call belongs.

             ECI_STATE_CANCEL
                  Cancel an ECI_STATE_CHANGED type of operation. No COMMAREA is
                  required for this request. The eci_luw_token field must
                  contain the token that was received during the
                  ECI_STATE_CHANGED call.

          eci_message_qualifier
                    Optional input parameter.

                    An integer field allowing you to identify each asynchronous
                    call if you are making more than one. If a callback routine
                    is specified, the value in this field is returned to the
                    callback routine during the notification process.

          eci_luw_token
                    Optional input and output parameter.

                    When a deferred status request is being set up
                    (eci_extend_mode set to ECI_STATE_CHANGED), the token
                    identifying the request is returned in the eci_luw_token
                    field.

                    When a deferred status request is being cancelled
                    (eci_extend_mode set to ECI_STATE_CANCEL), the
                    eci_luw_token field must contain the token that was
                    received during the ECI_STATE_CHANGED call.

                    This field is not used when other values of eci_extend_mode
                    are specified.

          eci_sysid
                    Required input parameter.

                    Reserved for future use, but this field should be
                    initialized with nulls before the start of each logical
                    unit of work.

          eci_version
                    Required input parameter.

                    The version of the ECI for which the application is coded.
                    In the CICS on Open Systems environment, only ECI_VERSION_1
                    may be specified. In other environments, you may use the
                    values ECI_VERSION_1 or ECI_VERSION_1A. All the facilities
                    of version 1 are available in version 1A. Facilities
                    available only in version 1A are noted where they occur.
                    (ECI_VERSION_0 is provided to allow applications written
                    for previous versions of the ECI to continue to execute,
                    but many of the facilities of CICS Client/Server
                    Programming are not available if eci_version has this
                    value.)

          eci_system_name
                    Optional input parameter.

                    An 8-character field that specifies the name of the server
                    for which status information is requested. Unused
                    characters should be padded with spaces. If supplied, it
                    should be one of the server names returned by
                    CICS_EciListSystems. The value may be supplied whenever
                    eci_luw_token is set to zero.

                    If the field is set to nulls, then a server, currently the
                    default server, is selected. You can find out the name of
                    the server from the eci_system_name field of the reply
                    solicitation call you use to get the result of this
                    asynchronous request. field.

          eci_callback
                    Optional input parameter.

                    A pointer to the routine to be called when the asynchronous
                    request completes. (The callback routine will be called
                    only if the return code is ECI_NO_ERROR, and the pointer is
                    not null.)

 Return codes

          See also the general list of return codes for CICS_ExternalCall in
          CICS_ExternalCall.

          If the return code is not ECI_NO_ERROR, the callback routine will not
          be called, and there will be no asynchronous reply for this request.

          ECI_NO_ERROR
                    The call completed successfully.

          ECI_ERR_INVALID_DATA_LENGTH
                    The value in eci_commarea_length field is outside the valid
                    range, or is inconsistent with the value in eci_commarea,
                    being zero for a non-null eci_commarea pointer, or non-zero
                    for a null eci_commarea pointer.

          ECI_ERR_INVALID_EXTEND_MODE
                    The value in eci_extend_mode field is not valid.

          ECI_ERR_LUW_TOKEN
                    The value supplied in  eci_luw_token is invalid.

          ECI_ERR_INVALID_DATA_AREA
                    Either the pointer to the ECI parameter block is invalid,
                    or the pointer supplied in eci_commarea is invalid.


ΓòÉΓòÉΓòÉ 7.5.5. ECI_GET_REPLY call type ΓòÉΓòÉΓòÉ

ECI_GET_REPLY call type

 Environment

          The ECI_GET_REPLY call type is available in all environments except
          DOS.

 Purpose

          The ECI_GET_REPLY call type provides a reply solicitation call to
          return information appropriate to any outstanding reply for any
          asynchronous request. If there is no such reply, ECI_ERR_NO_REPLY is
          returned. (To cause the application to wait until a reply is
          available, you should use call type ECI_GET_REPLY_WAIT instead.)

 ECI parameter block fields

          The ECI parameter block should be set to nulls before setting the
          input parameter fields.

          The following fields are the fields of the ECI parameter block that
          might be supplied as input.

          In the course of an  ECI_GET_REPLY call, the ECI parameter block is
          updated as follows:

           1. All the outputs from the reply, some of which overwrite input
              fields, are added. These fields are those that are output from
              the corresponding synchronous version of the asynchronous
              request.

           2. The eci_message_qualifier value supplied as input to the
              asynchronous request to which this reply relates is restored.

           3. Any inputs that are not updated become undefined, except the
              pointer to the COMMAREA. You should not use the contents of these
              fields again.

          eci_call_type
                    Required input parameter.

                    Must be set to ECI_GET_REPLY.

          eci_commarea
                    Optional input parameter.

                    A pointer to the area of storage where the application
                    receives the returned COMMAREA. The contents of the
                    returned commarea depend on the type of asynchronous call
                    to which a reply is being sought. For a program link call,
                    it is the COMMAREA expected to be returned from the called
                    program, if any. For a status information call, except when
                    eci_extend_mode has the value ECI_STATE_CANCEL, it is a
                    COMMAREA containing status information (see Status
                    information calls and ECI status block for more details).

                    If no COMMAREA is required, supply a null pointer and set
                    the length (specified in eci_commarea_length) to zero.

                    If the code page of the application is different from the
                    code page of the server, data conversion must be performed
                    at the server. To do this, you need to make use of
                    CICS-supplied resource conversion capabilities, such as the
                    DFHCNV macro definitions.

          eci_commarea_length
                    Required input parameter.

                    The length of the COMMAREA in bytes. This value may not
                    exceed 32500. (Some client-server combinations may allow
                    larger COMMAREAs, but this is not guaranteed to work as
                    part of CICS Family Client/Server Programming.)

                    If no COMMAREA is required, set this field to zero and
                    supply a null pointer in eci_commarea.

          eci_sysid
                    Required input parameter.

                    Reserved for future use, but this field should be
                    initialized with nulls before the start of each logical
                    unit of work.

          eci_version
                    Required input parameter.

                    The version of the ECI for which the application is coded.
                    In the CICS on Open Systems environment, only ECI_VERSION_1
                    may be specified. In other environments, you may use the
                    values ECI_VERSION_1 or ECI_VERSION_1A. All the facilities
                    of version 1 are available in version 1A. Facilities
                    available only in version 1A are noted where they occur.
                    (ECI_VERSION_0 is provided to allow applications written
                    for previous versions of the ECI to continue to execute,
                    but many of the facilities of CICS Client/Server
                    Programming are not available if eci_version has this
                    value.)

 Return codes

          See also the general list of return codes for CICS_ExternalCall in
          CICS_ExternalCall.

          ECI_NO_ERROR
                    The asynchronous request to which this reply relates
                    completed successfully.

          ECI_ERR_INVALID_DATA_LENGTH
                    The value in eci_commarea_length field is unacceptable for
                    one of the following reasons:

             o It is outside the valid range.

             o It is inconsistent with the value in eci_commarea, being zero
               for a non-null eci_commarea pointer, or non-zero for a null
               eci_commarea pointer.

             o It is not large enough for the output COMMAREA from the
               asynchronous request to which this reply relates.

                    In the last case, you can use the output
                    eci_commarea_length to allocate more storage for the
                    COMMAREA, and then use the output eci_message_qualifier (if
                    it identifies the asynchronous request uniquely) with an
                    ECI_GET_SPECIFIC_REPLY call type to retrieve the reply.

          ECI_ERR_NO_CICS
                    The CICS server specified in eci_system_name in the
                    asynchronous request to which this reply relates is not
                    available. No resources have been updated.

          ECI_ERR_CICS_DIED
                    A logical unit of work was to be begun or continued by the
                    asynchronous request to which this reply relates, but the
                    CICS server was no longer available. If eci_extend_mode was
                    ECI_EXTENDED, the changes are backed out, and the logical
                    unit of work ends. If eci_extend_mode was ECI_NO_EXTEND,
                    ECI_COMMIT, or ECI_BACKOUT, the application cannot
                    determine whether the changes have been committed or backed
                    out, and must log this condition to aid future manual
                    recovery.

          ECI_ERR_NO_REPLY
                    There was no outstanding reply.

          ECI_ERR_TRANSACTION_ABEND
                    The asynchronous request to which this reply relates caused
                    a program to be executed in the server, but the CICS
                    transaction that executed the requested program abended.
                    The abend code will be found in eci_abend_code. For
                    information about abend codes and their meaning, you should
                    consult the documentation for the server system to which
                    the request was directed.

          ECI_ERR_THREAD_CREATE_ERROR
                    The CICS server or client failed to create the thread to
                    process the asynchronous call to which this reply relates.

          ECI_ERR_RESOURCE_SHORTAGE
                    The server implementation or client did not have enough
                    resources to complete the asynchronous request to which
                    this reply relates.

          ECI_ERR_INVALID_DATA_AREA
                    Either the pointer to the ECI parameter block is invalid,
                    or the pointer supplied in eci_commarea is invalid.

          ECI_ERR_ROLLEDBACK
                    The asynchronous request to which this reply relates
                    attempted to commit a logical unit of work, but the server
                    was unable to commit the changes, and backed them out
                    instead.

          ECI_ERR_UNKNOWN_SERVER
                    The asynchronous request to which this reply relates
                    specified a server that could not be located. Only servers
                    returned by CICS_EciListSystems are acceptable.

          ECI_ERR_MAX_SESSIONS
                    There were not enough communication resources to satisfy
                    the asynchronous request to which this reply relates. You
                    should consult the documentation for your client or server
                    to see how to control communication resources.

          ECI_ERR_MAX_SYSTEMS
                    The asynchronous request to which this reply relates
                    attempted to start requests to more servers than your
                    configuration allows. You should consult the documentation
                    for your client or server to see how to control the number
                    of servers you can use.

          ECI_ERR_SECURITY_ERROR
                    You did not supply a valid combination of userid and
                    password on the asynchronous request to which this reply
                    relates, though the server expects it.


ΓòÉΓòÉΓòÉ 7.5.6. ECI_GET_REPLY_WAIT call type ΓòÉΓòÉΓòÉ

ECI_GET_REPLY_WAIT call type

 Environment

          The ECI_GET_REPLY_WAIT call type is available in all environments
          except DOS.

 Purpose

          The ECI_GET_REPLY_WAIT call type provides a reply solicitation call
          to return information appropriate to any outstanding reply for any
          asynchronous request. If there is no such reply, the application
          waits until there is. (In all environments except DOS, you can get an
          indication that no reply is available by using call type
          ECI_GET_REPLY instead.)

 ECI parameter block fields

          Same as for ECI_GET_REPLY, but eci_call_type must be set to
          ECI_GET_REPLY_WAIT.

 Return codes

          Same as for ECI_GET_REPLY, except that ECI_ERR_NO_REPLY cannot be
          returned.


ΓòÉΓòÉΓòÉ 7.5.7. ECI_GET_SPECIFIC_REPLY call type ΓòÉΓòÉΓòÉ

ECI_GET_SPECIFIC_REPLY call type

 Environment

          The ECI_GET_SPECIFIC_REPLY call type is available in all environments
          except DOS.

 Purpose

          The ECI_GET_SPECIFIC_REPLY call type provides a reply solicitation
          call to return information appropriate to any outstanding reply that
          matches the eci_message_qualifier input. If there is no such reply,
          ECI_ERR_NO_REPLY is returned. (To cause the application to wait until
          a reply is available, you should use call type ECI_GET_REPLY_WAIT
          instead.)

 ECI parameter block fields

          The ECI parameter block should be set to nulls before setting the
          input parameter fields.

          The following fields are the fields of the ECI parameter block that
          might be supplied as input.

          In the course of an  ECI_GET_REPLY call, the ECI parameter block is
          updated as follows:

           1. All the outputs from the reply, some of which overwrite input
              fields, are added. These fields are those that are output from
              the corresponding synchronous version of the asynchronous
              request.

           2. Any inputs that are not updated become undefined, except the
              pointer to the COMMAREA and the input eci_message_qualifier. You
              should not use the contents of these fields again.

          eci_call_type
                    Required input parameter.

                    Must be set to ECI_GET_SPECIFIC_REPLY.

          eci_commarea
                    Optional input parameter.

                    A pointer to the area of storage where the application
                    receives the returned COMMAREA. The contents of the
                    returned commarea depend on the type of asynchronous call
                    to which a reply is being sought. For a program link call,
                    it is the COMMAREA expected to be returned from the called
                    program, if any. For a status information call, except one
                    in which eci_extend_mode had the value ECI_STATE_CANCEL, it
                    is a COMMAREA containing status information (see Status
                    information calls and ECI status block for more details).

                    If the code page of the application is different from the
                    code page of the server, data conversion must be performed
                    at the server. To do this, you need to make use of
                    CICS-supplied resource conversion capabilities, such as the
                    DFHCNV macro definitions.

          eci_commarea_length
                    Required input parameter.

                    The length of the COMMAREA in bytes. This value may not
                    exceed 32500. (Some client-server combinations may allow
                    larger COMMAREAs, but this is not guaranteed to work as
                    part of CICS Family Client/Server Programming.)

          eci_message_qualifier
                    Required input parameter.

                    An integer field that identifies the asynchronous call for
                    which a reply is being solicited.

          eci_sysid
                    Required input parameter.

                    Reserved for future use, but this field should be
                    initialized with nulls before the start of each logical
                    unit of work.

          eci_version
                    Required input parameter.

                    The version of the ECI for which the application is coded.
                    In the CICS on Open Systems environment, only ECI_VERSION_1
                    may be specified. In other environments, you may use the
                    values ECI_VERSION_1 or ECI_VERSION_1A. All the facilities
                    of version 1 are available in version 1A. Facilities
                    available only in version 1A are noted where they occur.
                    (ECI_VERSION_0 is provided to allow applications written
                    for previous versions of the ECI to continue to execute,
                    but many of the facilities of CICS Client/Server
                    Programming are not available if eci_version has this
                    value.)

 Return codes

          See also the general list of return codes for CICS_ExternalCall in
          CICS_ExternalCall.

          ECI_NO_ERROR
                    The call completed successfully.

          ECI_ERR_INVALID_DATA_LENGTH
                    The value in eci_commarea_length field is unacceptable for
                    one of the following reasons:

             o It is outside the valid range.

             o It is inconsistent with the value in eci_commarea, being zero
               for a non-null eci_commarea pointer, or non-zero for a null
               eci_commarea pointer.

             o It is not large enough for the output COMMAREA from the
               asynchronous request to which this reply relates.

                    In the last case, you can use the output
                    eci_commarea_length to allocate more storage for the
                    COMMAREA, and then retry the ECI_GET_SPECIFIC_REPLY call.

          ECI_ERR_NO_CICS
                    The CICS server specified in eci_system_name in the
                    asynchronous request to which this reply relates is not
                    available. No resources have been updated.

          ECI_ERR_CICS_DIED
                    A logical unit of work was to be begun or continued by the
                    asynchronous request to which this reply relates, but the
                    CICS server was no longer available. If eci_extend_mode was
                    ECI_EXTENDED, the changes are backed out, and the logical
                    unit of work ends. If eci_extend_mode was ECI_NO_EXTEND,
                    ECI_COMMIT, or ECI_BACKOUT, the application cannot
                    determine whether the changes have been committed or backed
                    out, and must log this condition to aid future manual
                    recovery.

          ECI_ERR_NO_REPLY
                    There was no outstanding reply that matched the input
                    eci_message_qualifier.

          ECI_ERR_TRANSACTION_ABEND
                    The asynchronous request to which this reply relates caused
                    a program to be executed in the server, but the CICS
                    transaction that executed the requested program abended.
                    The abend code will be found in eci_abend_code. For
                    information about abend codes and their meaning, you should
                    consult the documentation for the server system to which
                    the request was directed.

          ECI_ERR_THREAD_CREATE_ERROR
                    The CICS server or client failed to create the thread to
                    process the asynchronous request to which this reply
                    relates.

          ECI_ERR_RESOURCE_SHORTAGE
                    The CICS server or client did not have enough resources to
                    complete the asynchronous request to which this reply
                    relates.

          ECI_ERR_INVALID_DATA_AREA
                    Either the pointer to the ECI parameter block is invalid,
                    or the pointer supplied in eci_commarea is invalid.

          ECI_ERR_ROLLEDBACK
                    The asynchronous request to which this reply relates
                    attempted to commit a logical unit of work, but the server
                    was unable to commit the changes, and backed them out
                    instead.

          ECI_ERR_UNKNOWN_SERVER
                    The asynchronous request to which this reply relates
                    specified a server that could not be located. Only servers
                    returned by CICS_EciListSystems are acceptable.

          ECI_ERR_MAX_SESSIONS
                    There were not enough communication resources to satisfy
                    the asynchronous request to which this reply relates. You
                    should consult the documentation for your client or server
                    to see how to control communication resources.

          ECI_ERR_MAX_SYSTEMS
                    The asynchronous request to which this reply relates
                    attempted to start requests to more servers than your
                    configuration allows. You should consult the documentation
                    for your client or server to see how to control the number
                    of servers you can use.

          ECI_ERR_SECURITY_ERROR
                    You did not supply a valid combination of userid and
                    password on the asynchronous request to which this reply
                    relates, though the server expects it.


ΓòÉΓòÉΓòÉ 7.5.8. ECI_GET_SPECIFIC_REPLY_WAIT call type ΓòÉΓòÉΓòÉ

ECI_GET_SPECIFIC_REPLY_WAIT call type

 Environment

          The ECI_GET_SPECIFIC_REPLY_WAIT call type is available in all
          environments except DOS.

 Purpose

          The ECI_GET_SPECIFIC_REPLY_WAIT call type provides a reply
          solicitation call to return information appropriate to any
          outstanding reply that matches the input eci_message_qualifier. If
          there is no such reply, the application waits until there is. (In all
          environments except DOS, you can get an indication that no reply is
          available by using call type ECI_GET_SPECIFIC_REPLY instead.)

 ECI parameter block fields

          Same as for ECI_GET_SPECIFIC_REPLY, but eci_call_type must be set to
          ECI_GET_SPECIFIC_REPLY_WAIT.

 Return codes

          Same as for ECI_GET_SPECIFIC_REPLY, except that ECI_ERR_NO_REPLY
          cannot be returned.


ΓòÉΓòÉΓòÉ 7.6. ECI status block ΓòÉΓòÉΓòÉ

The ECI status block is used in status information calls to pass information to
and from the ECI. It contains the following fields:

 ConnectionType
           An integer field specifying the type of system on which the
           application is running, with the following possible values:

    ECI_CONNECTED_NOWHERE
              Application is not connected to anything.

    ECI_CONNECTED_TO_CLIENT
              Application is running on a client system.

    ECI_CONNECTED_TO_SERVER
              Application is using a server implementation of the ECI.

 CicsServerStatus
           An integer field specifying the state of the CICS server, with the
           following possible values:

    ECI_SERVERSTATE_UNKNOWN
              The CICS server state could not be determined.

    ECI_SERVERSTATE_UP
              The CICS server is available to run programs.

    ECI_SERVERSTATE_DOWN
              The CICS server is not available to run programs.

 CicsClientStatus
           An integer field specifying the state of the client, with the
           following possible values:

    ECI_CLIENTSTATE_UNKNOWN
              The client state could not be determined.

    ECI_CLIENTSTATE_UP
              The client is available to receive ECI calls.

    ECI_CLIENTSTATE_INAPPLICABLE
              The application is using a server implementation of the ECI.


ΓòÉΓòÉΓòÉ 7.7. CICS_EciListSystems ΓòÉΓòÉΓòÉ

CICS_EciListSystems

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EciListSystems          Γöé NameSpace               Γöé
Γöé                    Γöé Systems                Γöé
Γöé                    Γöé List                 Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          The CICS_EciListSystems function provides a list of CICS servers to
          which CICS_ExternalCall requests may be directed. There is no
          guarantee that a communications link exists between the client and
          any server in the list, or that any of the servers is available to
          process requests.

          The list of servers is returned as an array of system information
          structures, one element for each CICS server. The structure is called
          CICS_EciSystem_t, and it defines the following fields.

          SystemName
                    A pointer to a null-terminated string specifying the name
                    of a CICS server. If the name is shorter than
                    CICS_ECI_SYSTEM_MAX, it is padded with nulls to a length of
                    CICS_ECI_SYSTEM_MAX + 1.

          Description
                    A pointer to a null-terminated string that provides a
                    description of the system, if one is available. If the
                    description is shorter than CICS_ECI_DESCRIPTION_MAX
                    characters, it is padded with nulls to a length of
                    CICS_ECI_DESCRIPTION_MAX + 1.

 Parameters

          NameSpace
                    A pointer reserved for future use. Ensure that this is a
                    null pointer.

          Systems
                    On entry to the function, this parameter specifies the
                    number of elements in the array provided in the List
                    parameter. On return it contains the actual number of
                    systems found.

          List
                    An array of CICS_EciSystem_t structures that are filled in
                    and returned by the function. The application must provide
                    the storage for the array, and must set the Systems
                    parameter to indicate the number of elements in the array.
                    The first name in the list is the default server. However,
                    the way in which the default is defined is operating system
                    dependent.

 Return codes

          ECI_NO_ERROR
                    The function completed successfully. The number of systems
                    found is at least one, and does not exceed the value
                    supplied as input in the Systems parameter.

          ECI_ERR_MORE_SYSTEMS
                    There was not enough space in the List array to store the
                    information. The supplied array has been filled, and the
                    Systems parameter has been updated to contain the total
                    number of systems found, so that you can reallocate an
                    array of suitable size and try the function again.

          ECI_ERR_NO_SYSTEMS
                    No CICS servers can be located. In this case, the value
                    returned in Systems is zero.

          ECI_ERR_NO_CICS
                    The client is not active.

          ECI_ERR_INVALID_DATA_LENGTH
                    The value specified in the Systems parameter is so large
                    that the length of storage for the List parameter exceeds
                    32767.

          ECI_ERR_CALL_FROM_CALLBACK
                    The call was made from a callback routine.

          ECI_ERR_SYSTEM_ERROR
                    An internal system error occurred.


ΓòÉΓòÉΓòÉ 8. External presentation interface ΓòÉΓòÉΓòÉ

This chapter provides reference information about the external presentation
interface (EPI).

The interface is described here in a language-independent manner, though the
names chosen for the elements of the interface-functions, parameters, data
structures, fields, constants, and so on-are similar to those provided for
programming. For language-dependent information, see Creating ECI and EPI
application programs.

Any restrictions applicable to particular operating environments are identified
under the functions to which they apply.

The chapter is organized as follows:

 Overview
 How to use the EPI
 EPI constants and data structures
 EPI functions
 EPI events
 3270 data streams for the EPI
 Microsoft Windows considerations.


ΓòÉΓòÉΓòÉ 8.1. Overview ΓòÉΓòÉΓòÉ

The EPI allows a non-CICS application program to have access to one or more
CICS servers. In each CICS server, the application can establish one or more
terminal resources. The application acts as the operator of these terminal
resources, starting CICS transactions, and sending and receiving standard 3270
data streams associated with those transactions.

The following points should be borne in mind when designing client/server
implementations using the EPI.

  1. A CICS transaction that sends data to an EPI application must not use the
     IMMEDIATE option of EXEC CICS RETURN.

  2. The EPI application can use the EPI to determine the default screen size
     of the terminal resource definition, but not the alternate screen size.

  3. The EPI application cannot use the EPI to determine whether it is to send
     or receive double byte character set (DBCS) data streams to or from the
     CICS transaction.

  4. The 3270 data streams produced by CICS transactions must not contain
     structured fields.

  5. If a CICS transaction is run with execution diagnostic facility (EDF)
     enabled at an EPI application's terminal resource, the events reported to
     the EPI application are different from those reported when EDF is not
     enabled.

  6. If a CICS transaction uses EXEC CICS START with the DELAY option to
     schedule transactions to a terminal resource autoinstalled by an EPI
     application, the EPI application should exercise caution in deleting the
     terminal resource, or delayed ATI requests might be lost. You should
     consult your server documentation to determine the effects of deleting a
     terminal resource when delayed ATI requests are outstanding.

 The application is responsible for the presentation of the 3270 data received.
 The application may present the data in the normal way by emulating a 3270
 terminal, or it may present a very different view. For example:

 o An OS/2 application may use Presentation Manager.
 o An application for the CICS on Opens Systems environment may use Motif.
 o A SunOS application may use Open Look.
 o An Apple application may use Macintosh Toolbox.


ΓòÉΓòÉΓòÉ 8.2. How to use the EPI ΓòÉΓòÉΓòÉ

The EPI provides a separate function name for each of its functions.


ΓòÉΓòÉΓòÉ 8.2.1. Initialization and termination ΓòÉΓòÉΓòÉ

Any application requiring to use the EPI must call the CICS_EpiInitialize
function to initialize the EPI. Until this call is made, no other EPI function
is allowed. The CICS_EpiInitialize function takes a parameter indicating the
version of the EPI for which the application was coded. This is to ensure that
existing applications continue to execute without change if the EPI is
extended.

Before an EPI application ends, it should call the CICS_EpiTerminate function
to terminate the EPI cleanly.


ΓòÉΓòÉΓòÉ 8.2.2. Listing the configured servers ΓòÉΓòÉΓòÉ

After calling CICS_EpiInitialize successfully, the application should call
CICS_EpiListSystems to check which CICS servers are configured for use by the
application.


ΓòÉΓòÉΓòÉ 8.2.3. Adding and deleting terminal resources ΓòÉΓòÉΓòÉ

The primary purpose of the EPI is to allow an application to appear to a CICS
server as one or more 3270 terminals. The application should make a
CICS_EpiAddTerminal call for each terminal resource it needs to define.

The application must specify the server in which the terminal resource is to be
installed, and may specify the terminal resource to be installed by supplying
one of the following:

 o The netname of an existing terminal resource in the server. This terminal
   resource should be one that is not currently in use.

 o The name of a model terminal definition. In this case a new terminal
   resource is autoinstalled.

 o Nothing. In this case the server generates a netname and autoinstalls a
   terminal resource with that name, using a default model terminal definition.

 Once an application has established its use of a terminal resource with
 CICS_EpiAddTerminal, no other application can use that terminal resource until
 the first application releases it with CICS_EpiDelTerminal.

 The CICS_EpiAddTerminal call returns a terminal index, which must be passed on
 subsequent EPI function calls to indicate the terminal resource to which the
 function is to apply. Each index identifies a combination of server and
 terminal resource. The terminal index supplied is the first available integer
 starting from 0. This allows the application to maintain a mapping between
 terminal indexes and terminal resource information, using array lookup.

 Terminal indexes are unique within an application, but not across
 applications, so each application gets terminal index zero for the first
 terminal it installs, and so on.

 Using terminal indexes shows an application with three terminal resources, one
 in one server and two in another. The application uses the terminal indexes to
 operate the terminal resources, sending and receiving 3270 data streams. The
 order of the indexes shows the order in which the terminal resources were
 installed with CICS_EpiAddTerminal.


  Using terminal indexes

 If a terminal resource is no longer required, it can be deleted by making a
 CICS_EpiDelTerminal call. This call can succeed only if the terminal resource
 is not currently running a transaction; if a transaction is in progress, the
 call returns an error code. Deleting a terminal resource is like signing off
 from the terminal by running the CESF transaction. When deletion is complete,
 the terminal index value becomes free and can be reissued by a subsequent
 CICS_EpiAddTerminal call. If the terminal resource was added by way of a model
 terminal definition, the CICS_EpiDelTerminal call also deletes the terminal
 resource from the server.


ΓòÉΓòÉΓòÉ 8.2.4. Starting transactions ΓòÉΓòÉΓòÉ

When an application has defined a terminal resource, it can start a transaction
from that terminal resource. To the CICS server it appears as if a terminal
user had typed a transaction code on the screen and pressed an AID key. To
start a transaction, the CICS_EpiStartTran function is called. There are two
ways of specifying the transaction to be started and the data to be associated
with it.

  1. Supply the transaction identifier as a parameter to the call (TransId),
     and supply any transaction data in the Data parameter.

  2. Combine a transaction identifier and transaction data into a 3270 data
     stream, and supply the data stream as a parameter to the call (Data).


ΓòÉΓòÉΓòÉ 8.2.5. Events and callbacks ΓòÉΓòÉΓòÉ

When an application has defined a terminal resource, several events can happen
to it because of actions in the CICS server, rather than actions of the
application. The application cannot predict when those events may happen, but
it is the responsibility of the application to collect and process the events
as appropriate. Events are held by the EPI in a first-in-first-out queue until
they are collected, one by one, by the application making calls to the
CICS_EpiGetEvent function. During such a call, the EPI puts information in a
CICS_EpiEventData_t structure to indicate the event that occurred and any
associated data. It also indicates whether there are more events still waiting
in the queue.

The application can synchronize the processing of these events with its other
activities in one of three ways:

 o Polling
 o Blocking
 o Callback notification.


ΓòÉΓòÉΓòÉ 8.2.5.1. Polling ΓòÉΓòÉΓòÉ

The CICS_EpiGetEvent call can be made in a polling mode by specifying
CICS_EPI_NOWAIT for the Wait parameter. If no event is waiting to be collected,
the function returns immediately with an error code. This is the mechanism that
you would have to adopt in a single-user single-threaded environment, such as
DOS, where the application might alternately poll the keyboard for user
activity and poll the EPI for event activity.


ΓòÉΓòÉΓòÉ 8.2.5.2. Blocking ΓòÉΓòÉΓòÉ

The CICS_EpiGetEvent call can be made in a blocking mode by specifying
CICS_EPI_WAIT for the Wait parameter. If no event is waiting to be collected,
the function waits and does not return until an event becomes available. You
could use this mechanism in a multithreaded environment, where a secondary
thread could be dedicated to event processing. It could also be used after a
notification by callback, because the event information is known to be
available.


ΓòÉΓòÉΓòÉ 8.2.5.3. Callback notification ΓòÉΓòÉΓòÉ

When the terminal resource is defined with the CICS_EpiAddTerminal call, the
optional parameter NotifyFn may be used to provide the address of a callback
routine that the EPI calls whenever an event occurs against that terminal
resource. Callback notification is not supported under DOS and Microsoft
Windows. Under DOS and Microsoft Windows, the parameter can be specified, but
it is ignored, and the application must poll for events.

Note:  Some compilers do not support the use of callback routines. Consult your
       compiler documentation for more information.

 An application should carry out the minimum of processing in its callback
 routine, and never block in the specified routine before returning to the EPI.
 The routine itself cannot make EPI calls. You decide what it should do when
 the notification is received. For example, in a multithreaded environment like
 OS/2, it might post a semaphore to signal another thread that an event has
 occurred. In a Presentation Manager environment, it might post a message to a
 window to indicate to the window procedure that an event has occurred. Other
 actions will be appropriate for other environments. In a CICS on Open Systems
 environment, only thread-safe facilities should be used.

 When the callback routine is called, it is passed a single parameter-the
 terminal index of the terminal resource against which the event occurred. This
 allows the same callback routine to be used for more than one terminal
 resource.


ΓòÉΓòÉΓòÉ 8.2.6. Processing the events ΓòÉΓòÉΓòÉ

On return from the CICS_EpiGetEvent function, the CICS_EpiEventData_t structure
contains the details of the event that occurred. The Event field in this
structure indicates the event, and can take one of the following values:

 o CICS_EPI_EVENT_SEND
 o CICS_EPI_EVENT_CONVERSE
 o CICS_EPI_EVENT_END_TRAN
 o CICS_EPI_EVENT_START_ATI
 o CICS_EPI_EVENT_END_TERM
 o CICS_EPI_EVENT_HELP.

 The application should attempt to process events as quickly as possible,
 because some events describe the state of the terminal resource. If these
 events are not processed, the application may receive unexpected error return
 codes when it tries to issue EPI functions, because the state maintained
 inside the EPI might not match the state maintained in the application. For
 example, an application can start a transaction only if the terminal resource
 is not currently running another transaction. The CICS_EPI_EVENT_END_TRAN
 event signals the end of a transaction, and so the application and the EPI
 enter a state in which new transactions can be started for that terminal
 resource. The CICS_EPI_EVENT_START_ATI event indicates that an ATI transaction
 has started at the terminal resource, and therefore that the terminal resource
 has entered a state in which the starting of transactions is no longer
 allowed. If the application calls CICS_EpiStartTran after the
 CICS_EPI_EVENT_START_ATI event has been notified, but before the event has
 been retrieved, the CICS_EpiStartTran call fails, even though, to the
 application, it may appear that it is still in a state in which it should
 succeed.


ΓòÉΓòÉΓòÉ 8.2.7. Sending and receiving data ΓòÉΓòÉΓòÉ

When a transaction sends data to a terminal resource, the EPI generates either
a CICS_EPI_EVENT_SEND event or a CICS_EPI_EVENT_CONVERSE event.

The CICS_EPI_EVENT_SEND event indicates that data was sent but that no reply is
required. Typically this would result from an EXEC CICS SEND command, but in
some servers it would result from an EXEC CICS CONVERSE command. (In the latter
case, a CICS_EPI_EVENT_CONVERSE event occurs later to tell the application to
send a data stream back to the transaction in the server.)

The CICS_EPI_EVENT_CONVERSE event indicates that a reply is required, and would
typically result from an EXEC CICS RECEIVE or EXEC CICS CONVERSE command. The
application should respond to this event by issuing a CICS_EpiReply call to
provide the response data. The CICS_EpiReply function should be issued only to
respond to a CICS_EPI_EVENT_CONVERSE event; if it is issued at any other time,
an error is returned.


ΓòÉΓòÉΓòÉ 8.2.8. Managing pseudoconversations ΓòÉΓòÉΓòÉ

CICS transactions can operate in a pseudoconversational mode. The conversation
between a terminal resource and a server is broken up into a number of
segments, each of which is a separate transaction. As each transaction ends, it
provides the name of the transaction to be run to process the next input from
the terminal resource. (It uses EXEC CICS RETURN with the TRANSID option to do
this.) The CICS_EPI_EVENT_END_TRAN event tells the application whether the
transaction just ended has specified a transaction to process the next input,
and which transaction has been specified. The application must not attempt to
start a different transaction, but must use CICS_EpiStartTran to start the
transaction specified by the CICS_EPI_EVENT_END_TRAN event.


ΓòÉΓòÉΓòÉ 8.2.9. Security in the EPI ΓòÉΓòÉΓòÉ

The EPI has no interface for the non-CICS application to supply userids or
passwords to the server. Not all CICS servers require the client to supply a
userid and password for EPI calls. Some CICS servers have configuration options
to decide whether the userid and password are required. You should consult the
publications for the appropriate server for more information.

Some client environments support the use of userids and passwords in files, so
that the userid and password need not be supplied by the non-CICS application.
Some client environments support the use of dialogs with the workstation
operator to determine userids and passwords. You should consult the
publications for the appropriate client environment for more information.

In the CICS on Open Systems environment, the operator might need DCE
authorization to use the EPI application, depending on the local configuration.
If the EPI program runs for a long time, for example longer than thirty
minutes, you must make sure that the credential lifetime and renewable lifetime
of the DCE principal are long enough to cover the maximum allowed duration of
the EPI program.

Authorization to use protected transactions can only be achieved by using
CICS_EpiStartTran for the CESN transaction, specifying userid and password.

Whether userids and passwords are encrypted depends on the communications
protocol being used between client and server.


ΓòÉΓòÉΓòÉ 8.3. EPI constants and data structures ΓòÉΓòÉΓòÉ

This section describes the constants and data structures that you will need to
use the EPI. They are referred to in EPI functions.


ΓòÉΓòÉΓòÉ 8.3.1. EPI constants ΓòÉΓòÉΓòÉ

The following constants are referred to symbolically in the descriptions of the
EPI data structures, functions, and events in this chapter. Their values are
given here to help you understand the descriptions. However, your code should
always use the symbolic names of EPI constants provided for the programming
language you are using.

Lengths of fields

 o CICS_EPI_SYSTEM_MAX (8)
 o CICS_EPI_DESCRIPTION_MAX (60)
 o CICS_EPI_NETNAME_MAX (8)
 o CICS_EPI_TRANSID_MAX (4)
 o CICS_EPI_ABEND_MAX (4)
 o CICS_EPI_DEVTYPE_MAX (16)
 o CICS_EPI_ERROR_MAX (60).

 Relating to TermIndex

 o CICS_EPI_TERM_INDEX_NONE  0xFFFF.
 Version numbers (See EPI versions)

 o CICS_EPI_VERSION_100
 o CICS_EPI_VERSION_101.


ΓòÉΓòÉΓòÉ 8.3.2. EPI data structures ΓòÉΓòÉΓòÉ

The following data structures are available for use with the EPI.

 o CICS_EpiSystem_t
 o CICS_EpiDetails_t
 o CICS_EpiEventData_t
 o CICS_EpiSysError_t.

 In the descriptions of the fields in the data structures, fields described as
 strings are null-terminated strings.


ΓòÉΓòÉΓòÉ 8.3.3. CICS_EpiSystem_t ΓòÉΓòÉΓòÉ

CICS_EpiSystem_t

 Purpose

           The CICS_EpiSystem_t structure contains the name and description of
          a CICS server. An array of these structures is returned from the
          CICS_EpiListSystems function.

 Fields

          SystemName
                    A string naming the CICS server. It can be passed as a
                    parameter to the CICS_EpiAddTerminal function, to identify
                    the CICS server in which the terminal resource should be
                    installed. If the name is shorter than CICS_EPI_SYSTEM_MAX
                    characters, it is padded with nulls to a length of
                    CICS_EPI_SYSTEM_MAX + 1.

          Description
                    A string giving a brief description of the server. If the
                    description is shorter than CICS_EPI_DESCRIPTION_MAX, it is
                    padded with nulls to a length of CICS_EPI_DESCRIPTION_MAX +
                    1.


ΓòÉΓòÉΓòÉ 8.3.4. CICS_EpiDetails_t ΓòÉΓòÉΓòÉ

CICS_EpiDetails_t

 Purpose

           The CICS_EpiDetails_t structure holds information about a terminal
          resource installed by CICS_EpiAddTerminal.

 Fields

          NetName
                    A string specifying the VTAM-style netname of the terminal
                    resource. If the name is shorter than CICS_EPI_NETNAME_MAX
                    characters, it is padded with nulls to a length of
                    CICS_EPI_NETNAME_MAX + 1.

          NumLines
                    The number of rows supported by the terminal resource.

          NumColumns
                    The number of columns supported by the terminal resource.

          MaxData
                    The maximum possible size of the data that CICS will send
                    to this terminal resource.

          ErrLastLine
                    1 if the terminal resource should display error messages on
                    its last row, 0 otherwise.

          ErrIntensify
                    1 if the terminal resource should display error messages
                    intensified, 0 otherwise.

          ErrColor
                    The 3270 attribute defining the color to be used to display
                    error messages.

          ErrHilight
                    The 3270 attribute defining the highlight value to be used
                    to display error messages.

          Hilight
                    1 if the terminal resource is defined to support extended
                    highlighting, 0 otherwise.

          Color
                    1 if the terminal resource is defined to support color, 0
                    otherwise.

          Printer
                    1 if the terminal resource is defined to be a printer, 0
                    otherwise.


ΓòÉΓòÉΓòÉ 8.3.5. CICS_EpiEventData_t ΓòÉΓòÉΓòÉ

CICS_EpiEventData_t

 Purpose

           The CICS_EpiEventData_t structure holds details of a
          terminal-related event. Not all fields are valid for all events, and
          fields that are not valid are set to nulls. This structure is an
          output from CICS_EpiGetEvent.

 Fields

          TermIndex
                    The terminal index for the terminal resource against which
                    this event occurred.

          Event
                    The event indicator; that is, one of the event codes listed
                    in EPI events.

          EndReason
                    The reason for termination, if the event is a
                    CICS_EPI_EVENT_END_TERM event (see page
                    CICS_EPI_EVENT_CONVERSE).

          TransId
                    A string specifying a transaction name. If the name is
                    shorter than CICS_EPI_TRANSID_MAX characters, it is padded
                    with spaces to this length, followed by a single null
                    character.

          AbendCode
                    A string specifying an abend code.

          Data
                    A pointer to a buffer that is updated with any terminal
                    data stream associated with the event.

          Size
                    The maximum size of the buffer addressed by Data. On return
                    from the CICS_EpiGetEvent call, this contains the actual
                    length of data returned.

          Note:  The Data and Size fields should be set before the call to
                 CICS_EpiGetEvent is made.


ΓòÉΓòÉΓòÉ 8.3.6. CICS_EpiSysError_t ΓòÉΓòÉΓòÉ

CICS_EpiSysError_t

 Purpose

           The CICS_EpiSysError_t structure holds system error information. It
          is an output of CICS_EpiGetSysError.

 Fields

          Cause
                    A value, specific to the operating environment, indicating
                    the cause of the last error.

          Value
                    A value, specific to the operating environment, indicating
                    the nature of the last error.

          Msg
                    A text message, specific to the operating environment,
                    describing the last error. If the message is shorter than
                    CICS_EPI_ERROR_MAX, it is padded with nulls to a length of
                    CICS_EPI_ERROR_MAX + 1.


ΓòÉΓòÉΓòÉ 8.4. EPI versions ΓòÉΓòÉΓòÉ

The following descriptions of EPI functions include information about two
versions of the EPI. You should consult the documentation for your client or
server environment to determine which versions of the EPI they provide. You
establish the version of the EPI that you need by using the Version parameter
on the CICS_EpiInitialize function.

The function described in the following sections is the function for
CICS_EPI_VERSION_101. If you initialize the EPI with CICS_EPI_VERSION_100, the
following restrictions apply:

 o The CICS_EpiInquireSystem function is not supported.

 o The return codes EPI_ERR_IN_CALLBACK, EPI_ERR_NULL_PARM, and
   EPI_ERR_SECURITY are not supported. EPI_ERR_FAILED will be returned instead.

 o The System parameter of CICS_EpiAddTerminal must specify a non-null string,
   as the mechanism for finding a default server is not supported. (If a null
   string is specified, CICS_EPI_ERR_SYSTEM is returned.)


ΓòÉΓòÉΓòÉ 8.5. EPI functions ΓòÉΓòÉΓòÉ

This section describes the functions provided by the EPI that can be called
from an application program:

 o CICS_EpiInitialize
 o CICS_EpiTerminate
 o CICS_EpiListSystems
 o CICS_EpiAddTerminal
 o CICS_EpiInquireSystem
 o CICS_EpiDelTerminal
 o CICS_EpiStartTran
 o CICS_EpiReply
 o CICS_EpiATIState
 o CICS_EpiSenseCode
 o CICS_EpiGetEvent
 o CICS_EpiGetSysError.

 Summary of EPI functions summarizes the functions of the interface, the
 parameters passed to each function, and the possible return codes from each
 function.

  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  Γöé Table 1. Summary of EPI functions                       Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé Function name         Γöé Parameters   Γöé Return codes:         Γöé
  Γöé                Γöé        Γöé CICS_EPI_           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EpiInitialize       Γöé Version    Γöé ERR_FAILED          Γöé
  Γöé                Γöé        Γöé ERR_IS_INIT          Γöé
  Γöé                Γöé        Γöé ERR_VERSION          Γöé
  Γöé                Γöé        Γöé ERR_IN_CALLBACK        Γöé
  Γöé                Γöé        Γöé NORMAL            Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EpiTerminate       Γöé none      Γöé ERR_FAILED          Γöé
  Γöé                Γöé        Γöé ERR_NOT_INIT         Γöé
  Γöé                Γöé        Γöé ERR_IN_CALLBACK        Γöé
  Γöé                Γöé        Γöé NORMAL            Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EpiListSystems      Γöé NameSpace   Γöé ERR_FAILED          Γöé
  Γöé                Γöé Systems    Γöé ERR_MORE_SYSTEMS       Γöé
  Γöé                Γöé List      Γöé ERR_NO_SYSTEMS        Γöé
  Γöé                Γöé        Γöé ERR_NOT_INIT         Γöé
  Γöé                Γöé        Γöé ERR_NULL_PARM         Γöé
  Γöé                Γöé        Γöé ERR_IN_CALLBACK        Γöé
  Γöé                Γöé        Γöé NORMAL            Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EpiAddTerminal      Γöé NameSpace   Γöé ERR_FAILED          Γöé
  Γöé                Γöé System     Γöé ERR_MAX_TERMS         Γöé
  Γöé                Γöé NetName    Γöé ERR_NOT_INIT         Γöé
  Γöé                Γöé DevType    Γöé ERR_SYSTEM          Γöé
  Γöé                Γöé NotifyFn    Γöé ERR_SECURITY         Γöé
  Γöé                Γöé Details    Γöé ERR_NULL_PARM         Γöé
  Γöé                Γöé TermIndex   Γöé ERR_IN_CALLBACK        Γöé
  Γöé                Γöé        Γöé NORMAL            Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EpiInquireSystem     Γöé TermIndex   Γöé ERR_BAD_INDEX         Γöé
  Γöé                Γöé System     Γöé ERR_FAILED          Γöé
  Γöé                Γöé        Γöé ERR_NOT_INIT         Γöé
  Γöé                Γöé        Γöé ERR_NULL_PARM         Γöé
  Γöé                Γöé        Γöé ERR_IN_CALLBACK        Γöé
  Γöé                Γöé        Γöé NORMAL            Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EpiDelTerminal      Γöé TermIndex   Γöé ERR_BAD_INDEX         Γöé
  Γöé                Γöé        Γöé ERR_FAILED          Γöé
  Γöé                Γöé        Γöé ERR_NOT_INIT         Γöé
  Γöé                Γöé        Γöé ERR_TRAN_ACTIVE        Γöé
  Γöé                Γöé        Γöé ERR_IN_CALLBACK        Γöé
  Γöé                Γöé        Γöé NORMAL            Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EpiStartTran       Γöé TermIndex   Γöé ERR_ATI_ACTIVE        Γöé
  Γöé                Γöé TransId    Γöé ERR_BAD_INDEX         Γöé
  Γöé                Γöé Data      Γöé ERR_FAILED          Γöé
  Γöé                Γöé Size      Γöé ERR_NO_DATA          Γöé
  Γöé                Γöé        Γöé ERR_NOT_INIT         Γöé
  Γöé                Γöé        Γöé ERR_TTI_ACTIVE        Γöé
  Γöé                Γöé        Γöé ERR_IN_CALLBACK        Γöé
  Γöé                Γöé        Γöé NORMAL            Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EpiReply         Γöé TermIndex   Γöé ERR_BAD_INDEX         Γöé
  Γöé                Γöé Data      Γöé ERR_FAILED          Γöé
  Γöé                Γöé Size      Γöé ERR_NO_CONVERSE        Γöé
  Γöé                Γöé        Γöé ERR_NO_DATA          Γöé
  Γöé                Γöé        Γöé ERR_NOT_INIT         Γöé
  Γöé                Γöé        Γöé ERR_IN_CALLBACK        Γöé
  Γöé                Γöé        Γöé NORMAL            Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EpiATIState        Γöé TermIndex   Γöé ERR_ATI_STATE         Γöé
  Γöé                Γöé ATIState    Γöé ERR_BAD_INDEX         Γöé
  Γöé                Γöé        Γöé ERR_FAILED          Γöé
  Γöé                Γöé        Γöé ERR_NOT_INIT         Γöé
  Γöé                Γöé        Γöé ERR_IN_CALLBACK        Γöé
  Γöé                Γöé        Γöé NORMAL            Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EpiSenseCode       Γöé TermIndex   Γöé ERR_BAD_INDEX         Γöé
  Γöé                Γöé SenseCode   Γöé ERR_FAILED          Γöé
  Γöé                Γöé        Γöé ERR_NOT_INIT         Γöé
  Γöé                Γöé        Γöé ERR_SENSE_CODE        Γöé
  Γöé                Γöé        Γöé ERR_IN_CALLBACK        Γöé
  Γöé                Γöé        Γöé NORMAL            Γöé
  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  Γöé Table 1. Summary of EPI functions                       Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EpiGetEvent        Γöé TermIndex   Γöé ERR_BAD_INDEX         Γöé
  Γöé                Γöé Wait      Γöé ERR_FAILED          Γöé
  Γöé                Γöé Event     Γöé ERR_MORE_DATA         Γöé
  Γöé                Γöé        Γöé ERR_MORE_EVENTS        Γöé
  Γöé                Γöé        Γöé ERR_NO_EVENT         Γöé
  Γöé                Γöé        Γöé ERR_NOT_INIT         Γöé
  Γöé                Γöé        Γöé ERR_WAIT           Γöé
  Γöé                Γöé        Γöé ERR_NULL_PARM         Γöé
  Γöé                Γöé        Γöé ERR_IN_CALLBACK        Γöé
  Γöé                Γöé        Γöé NORMAL            Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EpiGetSysError      Γöé TermIndex   Γöé ERR_NOT_INIT         Γöé
  Γöé                Γöé SysErr     Γöé ERR_BAD_INDEX         Γöé
  Γöé                Γöé        Γöé ERR_FAILED          Γöé
  Γöé                Γöé        Γöé ERR_NULL_PARM         Γöé
  Γöé                Γöé        Γöé ERR_IN_CALLBACK        Γöé
  Γöé                Γöé        Γöé NORMAL            Γöé
  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Refer to the definitions of the functions to discover the types and usage of
 the parameters, the data structures used by the functions, and the meanings of
 the return codes.


ΓòÉΓòÉΓòÉ 8.5.1. CICS_EpiInitialize ΓòÉΓòÉΓòÉ

CICS_EpiInitialize

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EpiInitialize           Γöé Version                Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          The CICS_EpiInitialize function initializes the EPI. All other EPI
          calls from this application are invalid before this call is made.

     Microsoft Windows only

     See Microsoft Windows considerations for further details of the use of
     this function in a Microsoft Windows environment.

 Parameters

          Version
                    The version of the EPI for which this application is coded.
                    This makes it possible for old applications to remain
                    compatible with future versions of the EPI. The version
                    described here is CICS_EPI_VERSION_101. (See EPI versions
                    for more information.)

                    The EPI uses this parameter only for input.

 Return codes

          CICS_EPI_ERR_FAILED
                    The function failed for an unexpected reason.

          CICS_EPI_ERR_IS_INIT
                    The EPI is already initialized.

          CICS_EPI_ERR_VERSION
                    The EPI cannot support the version requested.

          CICS_EPI_ERR_IN_CALLBACK
                    The function was called from a callback routine.

          CICS_EPI_NORMAL
                    The function completed successfully.


ΓòÉΓòÉΓòÉ 8.5.2. CICS_EpiTerminate ΓòÉΓòÉΓòÉ

CICS_EpiTerminate

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EpiTerminate           Γöé                    Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          The CICS_EpiTerminate function ends the application's use of the EPI,
          typically just before the application terminates. All other EPI calls
          (except for CICS_EpiInitialize) are invalid when this call has
          completed.

          The application should issue CICS_EpiDelTerminal calls before
          terminating, to ensure that any terminal resources are deleted.

 Parameters

          None.

 Return codes

          CICS_EPI_ERR_FAILED
                    The function failed for an unexpected reason.

          CICS_EPI_ERR_NOT_INIT
                    CICS_EpiInitialize has not been executed.

          CICS_EPI_ERR_IN_CALLBACK
                    The function was called from a callback routine.

          CICS_EPI_NORMAL
                    The function completed successfully.


ΓòÉΓòÉΓòÉ 8.5.3. CICS_EpiListSystems ΓòÉΓòÉΓòÉ

CICS_EpiListSystems

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EpiListSystems          Γöé NameSpace               Γöé
Γöé                    Γöé Systems                Γöé
Γöé                    Γöé List                 Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          The CICS_EpiListSystems function returns a list of CICS servers that
          are candidates to act as servers for EPI requests. There is no
          guarantee that a communications link exists between the client and
          any server in the list, or that any of the servers is available to
          process requests.

          The list is returned as an array of system information structures,
          one element for each CICS server. See CICS_EpiSystem_t for the
          contents of the structure.

          EPI applications should call this function immediately after each
          CICS_EpiInitialize call made to determine which CICS servers are
          available.

 Parameters

          NameSpace
                    A pointer reserved for future use. Ensure that this is a
                    null pointer.

          Systems
                    A pointer to a number. On entry to the function, this
                    number specifies the number of elements in the array
                    specified in the List parameter. This value should
                    accurately reflect the amount of storage that is available
                    to the EPI to store the result. On return, it contains the
                    actual number of servers found.

                    The EPI uses this parameter for both input and output.

          List
                    An array of CICS_EpiSystem_t structures that are filled in
                    and returned by the function. The application should
                    provide the storage for the array and must set the Systems
                    parameter to indicate the number of elements in the array.
                    The first name in the list is the default server. However,
                    the way in which the default is defined is operating system
                    dependent.

                    The EPI uses this parameter only for output.

 Return codes

          CICS_EPI_ERR_FAILED
                    The function failed for an unexpected reason.

          CICS_EPI_ERR_MORE_SYSTEMS
                    There was not enough space in the List array to store the
                    details of all the CICS servers found. The supplied array
                    has been filled, and the Systems parameter has been updated
                    to contain the total number of servers found, thus allowing
                    you to reallocate an array of suitable size and try the
                    function again.

          CICS_EPI_ERR_NO_SYSTEMS
                    No CICS servers can be located. In this case, the value
                    returned in Systems is zero.

          CICS_EPI_ERR_NOT_INIT
                    CICS_EpiInitialize has not been executed.

          CICS_EPI_ERR_NULL_PARM
                    Systems is a null pointer.

          CICS_EPI_ERR_IN_CALLBACK
                    The function was called from a callback routine.

          CICS_EPI_NORMAL
                    The function completed successfully. The number of systems
                    found is at least one, and does not exceed the value
                    supplied as input in the Systems parameter.


ΓòÉΓòÉΓòÉ 8.5.4. CICS_EpiAddTerminal ΓòÉΓòÉΓòÉ

CICS_EpiAddTerminal

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EpiAddTerminal          Γöé NameSpace               Γöé
Γöé                    Γöé System                Γöé
Γöé                    Γöé NetName                Γöé
Γöé                    Γöé DevType                Γöé
Γöé                    Γöé NotifyFn               Γöé
Γöé                    Γöé Details                Γöé
Γöé                    Γöé TermIndex               Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          The CICS_EpiAddTerminal function installs a new terminal resource, or
          reserves an existing terminal resource, for the application's use. It
          provides a terminal index, which should be used to identify the
          terminal resource on all further EPI calls. It also provides the
          information defined in the CICS_EpiDetails_t data structure.

     Microsoft Windows only

     See Microsoft Windows considerations for further details of the use of
     this function in a Microsoft Windows environment.

 Parameters

          NameSpace
                    A pointer reserved for future use. Ensure that this is a
                    null pointer.

          System
                    A pointer to a null-terminated string that specifies the
                    name of the server in which the terminal resource is to be
                    installed or reserved. If the name is shorter than
                    CICS_EPI_SYSTEM_MAX characters, it must be padded with
                    nulls to a length of CICS_EPI_SYSTEM_MAX + 1.

                    If the string is all nulls, then a server, currently the
                    default server, is selected by the EPI. To determine the
                    name of the server chosen, use CICS_EpiInquireSystem.
                    (Specifying a null string is allowed only if the EPI was
                    initialized with EPI_VERSION_101.)

                    The EPI uses this parameter only for input.

          NetName
                    A pointer to a null-terminated string that specifies the
                    name of the terminal resource to be installed or reserved,
                    or null. The interpretation of this name is
                    server-dependent.

                    If a string is supplied that is shorter than
                    CICS_EPI_NETNAME_MAX, it must be padded with nulls to a
                    length of CICS_EPI_NETNAME_MAX + 1.

                    The string is transmitted to the server without conversion
                    to uppercase.

                    The use of NetName is as follows:

              1. If a name is supplied using the NetName, and it matches the
                 name of an existing terminal resource in the server, the
                 server attempts to reserve that terminal resource.

              2. If a name is supplied, but it does not match the name of an
                 existing terminal resource in the server, the processing
                 depends on the server as follows:

                o In a CICS on Open Systems server, the server installs a
                  resource using a default model terminal definition, and gives
                  it the input name.

                o On other CICS servers, the server installs a terminal
                  resource using the model terminal definition specified by the
                  DevType parameter described below, and gives it the input
                  name. (If DevType is a null pointer, CICS_EPI_ERR_FAILED is
                  returned.)

              3. If NetName is a null pointer, then a terminal resource is
                 installed using the model terminal definition specified in
                 DevType, or a default model terminal definition if DevType is
                 a null pointer. The name of the terminal resource is returned
                 in the NetName field of the CICS_EpiDetails_t structure.

                    The EPI uses this parameter only for input.

          DevType
                    A pointer to a null-terminated string that is used in the
                    server to select a model terminal definition from which a
                    terminal resource definition is generated, or a null
                    pointer.

                    If a string is supplied that is shorter than
                    CICS_EPI_DEVTYPE_MAX characters, it should be padded with
                    nulls to a length of CICS_EPI_DEVTYPE_MAX + 1.

                    The string is transmitted to the server without conversion
                    to uppercase.

                    The EPI uses this parameter only for input.

          NotifyFn
                    A pointer to a callback routine that is called whenever an
                    event occurs for the terminal resource, such as the arrival
                    of an ATI request. If a callback routine is not required,
                    this parameter should be set to null.

                    The EPI uses this parameter only for input.

     DOS and Microsoft Windows The function is ignored and never called even if
     specified.

          Details
                    A pointer to the CICS_EpiDetails_t structure that on return
                    contains various details about the terminal resource that
                    was installed or reserved.

                    The EPI uses the fields in this structure only for output.

          TermIndex
                    A pointer to a terminal index for the terminal resource
                    just installed or reserved. The returned terminal index
                    must be used as input to all further EPI function calls to
                    identify the terminal resource to which the function is
                    directed. The terminal index supplied is the first
                    available integer starting from 0.

                    The EPI uses this parameter only for output.

 Return codes

          CICS_EPI_ERR_FAILED
                    The function failed for an unexpected reason.

          CICS_EPI_ERR_MAX_TERMS
                    The maximum number of terminal resources supported by the
                    EPI for this process has been reached.

          CICS_EPI_ERR_NOT_INIT
                    CICS_EpiInitialize has not been executed.

          CICS_EPI_ERR_SYSTEM
                    The specified server is not known to the client.

          CICS_EPI_ERR_SECURITY
                    The server rejected the attempt for security reasons.

          CICS_EPI_ERR_NULL_PARM
                    TermIndex was a null pointer.

          CICS_EPI_ERR_IN_CALLBACK
                    The function was called from a callback routine.

          CICS_EPI_NORMAL
                    The function completed successfully.


ΓòÉΓòÉΓòÉ 8.5.5. CICS_EpiInquireSystem ΓòÉΓòÉΓòÉ

CICS_EpiInquireSystem

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EpiInquireSystem         Γöé TermIndex               Γöé
Γöé                    Γöé System                Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          The CICS_EpiInquireSystem function returns the name of the server on
          which a given terminal resource (identified by its terminal index) is
          installed.

 Parameters

          TermIndex
                    The terminal index of the terminal resource whose location
                    is to be determined.

                    The EPI uses this parameter only for input.

          System
                    A pointer to a string of length CICS_ECI_SYSTEM_MAX + 1 in
                    which the name of the server will be returned.

                    The EPI uses this parameter only for output.

 Return codes

          CICS_EPI_ERR_BAD_INDEX
                    The TermIndex value is not a valid terminal index.

          CICS_EPI_ERR_FAILED
                    The function failed for an unexpected reason.

          CICS_EPI_ERR_NOT_INIT
                    CICS_EpiInitialize has not been executed.

          CICS_EPI_ERR_NULL_PARM
                    System was a null pointer.

          CICS_EPI_ERR_IN_CALLBACK
                    The function was called from a callback routine.

          CICS_EPI_NORMAL
                    The function completed successfully. The name of the server
                    is returned in the System parameter padded with nulls to a
                    length of CICS_EPI_SYSTEM_MAX +1.


ΓòÉΓòÉΓòÉ 8.5.6. CICS_EpiDelTerminal ΓòÉΓòÉΓòÉ

CICS_EpiDelTerminal

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EpiDelTerminal          Γöé TermIndex               Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          The CICS_EpiDelTerminal function deletes a previously added terminal
          resource. The application should not consider the deletion complete
          until it receives the corresponding CICS_EPI_EVENT_END_TERM event. A
          call to this function fails if the terminal resource is currently
          running a transaction. To ensure that a terminal resource is deleted,
          the application must wait until the current transaction finishes and
          process all outstanding events before issuing the CICS_EpiDelTerminal
          call.

          If the terminal resource was autoinstalled, its definition is deleted
          from the server. When a CICS_EpiDelTerminal call has completed
          successfully for a terminal resource, use of the terminal index is
          restricted to CICS_EpiGetEvent and CICS_EpiGetSysError calls until
          the application has received the corresponding
          CICS_EPI_EVENT_END_TERM event.

 Parameters

          TermIndex
                    The terminal index of the terminal resource to be deleted.

                    The EPI uses this parameter only for input.

 Return codes

          CICS_EPI_ERR_BAD_INDEX
                    The TermIndex value is not a valid terminal index.

          CICS_EPI_ERR_FAILED
                    The function failed for an unexpected reason.

          CICS_EPI_ERR_NOT_INIT
                    CICS_EpiInitialize has not been executed.

          CICS_EPI_ERR_TRAN_ACTIVE
                    A transaction is currently running against the terminal
                    resource, or there are unprocessed events for the terminal
                    resource.

          CICS_EPI_ERR_IN_CALLBACK
                    The function was called from a callback routine.

          CICS_EPI_NORMAL
                    The function completed successfully.


ΓòÉΓòÉΓòÉ 8.5.7. CICS_EpiStartTran ΓòÉΓòÉΓòÉ

CICS_EpiStartTran

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EpiStartTran           Γöé TermIndex               Γöé
Γöé                    Γöé TransId                Γöé
Γöé                    Γöé Data                 Γöé
Γöé                    Γöé Size                 Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          The CICS_EpiStartTran function starts a new transaction from a
          terminal resource, or continues a pseudoconversation.

          o Starting a new transaction-do this after CICS_EpiAddTerminal, or
            after a CICS_EPI_EVENT_END_TRAN event indicated that the previous
            transaction did not specify a transaction to process the next input
            from the terminal resource.

          o Continuing a pseudoconversation-do this after a
            CICS_EPI_EVENT_END_TRAN event that indicated that the previous
            transaction specified did specify a transaction to process the next
            input from the terminal resource.

          If the call is successful, no further start requests can be issued
          for this terminal resource until the transaction ends; this is
          indicated by the CICS_EPI_EVENT_END_TRAN event.

 Parameters

          TermIndex
                    The terminal index of the terminal resource that is to run
                    the transaction.

                    The EPI uses this parameter only for input.

          TransId
                    A pointer to a string specifying the transaction to be run,
                    or the null pointer. If a new transaction is being started,
                    and this input is the null pointer, the name of the
                    transaction is extracted from the data stream supplied in
                    the Data parameter. If a pseudoconversation is being
                    continued, and the pointer is not null, the string must be
                    the name of the transaction returned in the preceding
                    CICS_EPI_EVENT_END_TRAN event for this terminal resource.
                    If the pointer is not null, and the string is shorter than
                    CICS_EPI_TRANSID_MAX characters, it should be padded with
                    spaces to this length.

                    The EPI uses this parameter only for input.

          Data
                    A pointer to the 3270 data stream to be associated with the
                    transaction. This parameter must not be a null pointer,
                    because the data stream must contain at least an AID byte.

                    If a new transaction is being started, and the TransId
                    parameter is the null pointer, the data stream must be at
                    least 4 bytes long, must contain the name of the
                    transaction to be started, and might contain data to be
                    supplied to the transaction on its first EXEC CICS RECEIVE
                    command.

                    If a new transaction is being started, and the TransId
                    parameter is not the null pointer, the data stream might be
                    only one  byte (an AID byte), or 3 bytes (an AID byte and a
                    cursor address), or longer than 3 bytes (an AID byte, a
                    cursor address, and data and SBA commands). In the last
                    case, the data is supplied to the transaction program on
                    the first EXEC CICS RECEIVE command.

                    If a pseudoconversation is being continued, the data stream
                    might be only one byte (an AID byte), or 3 bytes (an AID
                    byte and a cursor address), or longer than 3 bytes (an AID
                    byte, a cursor address, and data and SBA commands). In the
                    last case the data is supplied to the transaction program
                    on the first EXEC CICS RECEIVE command.

                    The details of the format of 3270 data streams for CICS are
                    described in 3270 data streams for the EPI.

                    The EPI uses this parameter only for input.

          Size
                    The size in bytes of the initial data to be passed to the
                    transaction.

                    The EPI uses this parameter only for input.

          Note:  The application might expect a terminal resource to be free to
                 start a transaction and yet get an unexpected return code of
                 CICS_EPI_ERR_ATI_ACTIVE from a call to CICS_EpiStartTran. If
                 this happens, it means that the EPI has started an ATI request
                 against the terminal resource and issued the corresponding
                 CICS_EPI_EVENT_START_ATI event, but the application has not
                 yet retrieved the event by issuing a CICS_EpiGetEvent call.

 Return codes

          CICS_EPI_ERR_ATI_ACTIVE
                    An ATI transaction is active for this terminal resource.

          CICS_EPI_ERR_BAD_INDEX
                    The TermIndex value is not a valid terminal index.

          CICS_EPI_ERR_FAILED
                    The function failed for an unexpected reason.

          CICS_EPI_ERR_NO_DATA
                    No initial data was supplied.

          CICS_EPI_ERR_NOT_INIT
                    CICS_EpiInitialize has not been executed.

          CICS_EPI_ERR_TTI_ACTIVE
                    A transaction started from the EPI is already active for
                    this terminal resource.

          CICS_EPI_ERR_IN_CALLBACK
                    The function was called from a callback routine.

          CICS_EPI_NORMAL
                    The function completed successfully.


ΓòÉΓòÉΓòÉ 8.5.8. CICS_EpiReply ΓòÉΓòÉΓòÉ

CICS_EpiReply

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EpiReply             Γöé TermIndex               Γöé
Γöé                    Γöé Data                 Γöé
Γöé                    Γöé Size                 Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          The CICS_EpiReply function sends data from a terminal resource to a
          CICS transaction. It should only be issued in response to a
          CICS_EPI_EVENT_CONVERSE event.

 Parameters

          TermIndex
                    The terminal index of the terminal resource from which the
                    data is being sent.

                    The EPI uses this parameter only for input.

          Data
                    A pointer to the 3270 data stream to be sent to the
                    transaction. This parameter must not be a null pointer,
                    because the data stream must contain at least an AID byte.
                    The data stream might be one byte (an AID byte), 3 bytes
                    (an AID byte and a cursor address), or more than 3 bytes
                    (an AID byte, a cursor address, and data and SBA commands).
                    In the last case, what follows the cursor address is
                    supplied to the transaction program on the first EXEC CICS
                    RECEIVE command.

                    The EPI uses this parameter only for input.

          Size
                    The size of the data in bytes.

                    The EPI uses this parameter only for input.

 Return codes

          CICS_EPI_ERR_BAD_INDEX
                    The TermIndex value is not a valid terminal index.

          CICS_EPI_ERR_FAILED
                    The function failed for an unexpected reason.

          CICS_EPI_ERR_NO_CONVERSE
                    No reply is expected by the terminal resource.

          CICS_EPI_ERR_NO_DATA
                    No reply data was supplied.

          CICS_EPI_ERR_NOT_INIT
                    CICS_EpiInitialize has not been executed.

          CICS_EPI_ERR_IN_CALLBACK
                    The function was called from a callback routine.

          CICS_EPI_NORMAL
                    The function completed successfully.


ΓòÉΓòÉΓòÉ 8.5.9. CICS_EpiATIState ΓòÉΓòÉΓòÉ

CICS_EpiATIState

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EpiATIState            Γöé TermIndex               Γöé
Γöé                    Γöé ATIState               Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          The CICS_EpiATIState function allows the calling application to query
          and alter the way in which ATI requests for a terminal resource are
          handled. If ATI requests are enabled (CICS_EPI_ATI_ON) and an ATI
          request is issued in the server, the request is started when the
          terminal resource becomes free. If ATI requests are held
          (CICS_EPI_ATI_HOLD), any ATI requests issued are queued, and started
          when ATI requests are next enabled.

          The state for ATI requests after a CICS_EpiAddTerminal call is
          CICS_EPI_ATI_HOLD. The EPI application may change the state to
          CICS_EPI_ATI_ON when it is ready to allow ATI requests to be
          processed. (The server also maintains a ATI state for terminal
          resources, which is independent of the ATI state maintained in the
          EPI. Changes to the ATI state on the server do not affect the ATI
          status in the EPI.)

 Parameters

          TermIndex
                    The terminal index of the terminal resource whose ATI state
                    is required.

                    The EPI uses this parameter only for input.

          ATIState
                    The EPI uses this parameter for both input and output
                    depending on the input value as follows:

             CICS_EPI_ATI_ON
                       Enable ATI requests, and return the previous ATI state
                       in this parameter.

             CICS_EPI_ATI_HOLD
                       Hold ATI requests until they are next enabled, and
                       return the previous ATI state in this parameter.

             CICS_EPI_ATI_QUERY
                       Do not change the ATI state; just return the current
                       state in this parameter.

 Return codes

          CICS_EPI_ERR_ATI_STATE
                    An invalid ATIState value was provided.

          CICS_EPI_ERR_BAD_INDEX
                    The TermIndex value is not a valid terminal index.

          CICS_EPI_ERR_FAILED
                    The function failed for an unexpected reason.

          CICS_EPI_ERR_NOT_INIT
                    CICS_EpiInitialize has not been executed.

          CICS_EPI_ERR_IN_CALLBACK
                    The function was called from a callback routine.

          CICS_EPI_NORMAL
                    The function completed successfully.


ΓòÉΓòÉΓòÉ 8.5.10. CICS_EpiSenseCode ΓòÉΓòÉΓòÉ

CICS_EpiSenseCode

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EpiSenseCode           Γöé TermIndex               Γöé
Γöé                    Γöé SenseCode               Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          In the CICS on Open Systems environment, the CICS_EpiSenseCode
          function allows the calling application to inform the EPI of any
          errors in the 3270 data sent by a transaction.

          In other environments, the function has no effect.

 Parameters

          TermIndex
                    The terminal index of the terminal resource for which the
                    error is to be raised.

                    The EPI uses this parameter only for input.

          SenseCode
                    The sense code failure reason, which can be one of the
                    following values:

             CICS_EPI_SENSE_OPCHECK
                       Errors were detected in the 3270 data stream.

             CICS_EPI_SENSE_REJECT
                       Invalid 3270 commands were received.

                    The EPI uses this parameter only for input.

 Return codes

          CICS_EPI_ERR_BAD_INDEX
                    The TermIndex value is not a valid terminal index.

          CICS_EPI_ERR_FAILED
                    The function failed for an unexpected reason.

          CICS_EPI_ERR_NOT_INIT
                    CICS_EpiInitialize has not been executed.

          CICS_EPI_ERR_SENSE_CODE
                    An invalid sense code was provided.

          CICS_EPI_ERR_IN_CALLBACK
                    The function was called from a callback routine.

          CICS_EPI_NORMAL
                    The function completed successfully.


ΓòÉΓòÉΓòÉ 8.5.11. CICS_EpiGetEvent ΓòÉΓòÉΓòÉ

CICS_EpiGetEvent

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EpiGetEvent            Γöé TermIndex               Γöé
Γöé                    Γöé Wait                 Γöé
Γöé                    Γöé Event                 Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          The CICS_EpiGetEvent function obtains information about an event that
          has occurred for a terminal resource.

          Remember that this call may be attempted only from the application,
          not from the callback routine.

     Microsoft Windows only

     In a Microsoft Windows environment, the application should call this
     function after receiving a message with wParam set to CICS_EPI_WIN_EVENT.
     See Microsoft Windows considerations for further details of the use of
     this function in a Microsoft Windows environment, including the format of
     Windows messages posted by the EPI.

 Parameters

          TermIndex
                    The terminal index of the terminal resource for which to
                    obtain an event. This can be set to the constant
                    CICS_EPI_TERM_INDEX_NONE to indicate that the next event
                    for any terminal resource used by this application is to be
                    returned. The application can examine the TermIndex field
                    in the returned CICS_EpiEventData_t structure to determine
                    the terminal resource against which the event was
                    generated.

                    The EPI uses this parameter for both input and output.

          Wait
                    An indication of what should happen if no event has been
                    generated for the terminal resource. One of the following
                    values should be used:

             CICS_EPI_WAIT
                       Do not return until the next event occurs. (This value
                       should not be used in the Microsoft Windows or DOS
                       environments.)

             CICS_EPI_NOWAIT
                       Return immediately with an error code. This option is
                       used if the application elects to poll for events.

                    The EPI uses this parameter only for input.

          Event
                    A pointer to a CICS_EpiEventData_t structure that on return
                    contains the details of the event that occurred. The Data
                    field in the structure should be set to point to the data
                    buffer that is updated with any terminal data stream
                    associated with the event. The Size field should be set to
                    indicate the maximum size of this buffer, and is updated to
                    contain the actual length of data returned.

 Return codes

          CICS_EPI_ERR_BAD_INDEX
                    The TermIndex value is not a valid terminal index.

          CICS_EPI_ERR_FAILED
                    The function failed for an unexpected reason.

          CICS_EPI_ERR_MORE_DATA
                    The supplied data buffer was not large enough to contain
                    the terminal data; the data has been truncated.

          CICS_EPI_ERR_MORE_EVENTS
                    An event was successfully obtained, but there are more
                    events outstanding against this terminal resource.

          CICS_EPI_ERR_NO_EVENT
                    No events are outstanding for this terminal resource.

          CICS_EPI_ERR_NOT_INIT
                    CICS_EpiInitialize has not been executed.

          CICS_EPI_ERR_WAIT
                    The Wait parameter is not valid.

          CICS_EPI_ERR_NULL_PARM
                    Event is a null pointer.

          CICS_EPI_ERR_IN_CALLBACK
                    The function was called from a callback routine.

          CICS_EPI_NORMAL
                    The function completed successfully, and there are no more
                    events.


ΓòÉΓòÉΓòÉ 8.5.12. CICS_EpiGetSysError ΓòÉΓòÉΓòÉ

CICS_EpiGetSysError

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EpiGetSysError          Γöé TermIndex               Γöé
Γöé                    Γöé SysErr                Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          The CICS_EpiGetSysError function obtains detailed information
          describing the last error that occurred when the CICS_EPI_ERR_FAILED
          return code was generated. The values returned in the Cause and Value
          fields in the supplied SysErr parameter can be used to further
          qualify the return code from any other EPI function. These values are
          environment-dependent. You might need to consult documentation for
          your client environment, and the documentation for the appropriate
          CICS server.

          The Msg field in the supplied SysErr parameter may return a message,
          specific to the operating environment, describing the error that
          occurred. If no message is available, this field is set to nulls.

 Parameters

          TermIndex
                    The terminal index of the terminal resource for which to
                    obtain the detailed error code. This parameter may be set
                    to the constant CICS_EPI_TERM_INDEX_NONE, if further error
                    information associated with a CICS_EpiInitialize,
                    CICS_EpiTerminate, CICS_EpiListSystems, or
                    CICS_EpiAddTerminal call is required.

                    The EPI uses this parameter only for input.

          SysErr
                    A pointer to a CICS_EpiSysError_t structure that on return
                    contains the system error information.

                    The EPI uses the structure only for output.

 Return codes

          CICS_EPI_ERR_NOT_INIT
                    CICS_EpiInitialize has never been called. (If a
                    CICS_EpiInitialize call is made and fails,
                    CICS_EpiGetSysError will still succeed.)

          CICS_EPI_ERR_BAD_INDEX
                    The TermIndex value is not a valid terminal index.

          CICS_EPI_ERR_FAILED
                    The function failed for an unexpected reason.

          CICS_EPI_ERR_NULL_PARM
                    SysErr is a null pointer.

          CICS_EPI_ERR_IN_CALLBACK
                    The function was called from a callback routine.

          CICS_EPI_NORMAL
                    The function completed successfully.


ΓòÉΓòÉΓòÉ 8.6. EPI events ΓòÉΓòÉΓòÉ

EPI events occur when CICS has data to pass to the EPI application. The
application can handle EPI events in a variety of ways. (See Events and
callbacks.) Whichever mechanism is used, the data from CICS is obtained by
calling CICS_EpiGetEvent.


ΓòÉΓòÉΓòÉ 8.6.1. CICS_EPI_EVENT_SEND ΓòÉΓòÉΓòÉ

CICS_EPI_EVENT_SEND

 Purpose

          The CICS_EPI_EVENT_SEND event indicates that a transaction has sent
          some 3270 data to a terminal resource, typically as a result of an
          EXEC CICS SEND command. No reply is expected, and none should be
          attempted.

          (The reply might be data from the transaction, or it might be
          messages produced by the server, including error messages. You should
          consult your server documentation to see what messages are possible.)

 Fields completed

          Event
                    The CICS_EPI_EVENT_SEND event code.

          Data
                    A pointer to the buffer that is updated to contain the data
                    sent by the transaction. See 3270 data streams for the EPI
                    for details of the data stream format.

          Size
                    The length of the data in the Data buffer.


ΓòÉΓòÉΓòÉ 8.6.2. CICS_EPI_EVENT_CONVERSE ΓòÉΓòÉΓòÉ

CICS_EPI_EVENT_CONVERSE

 Purpose

          The CICS_EPI_EVENT_CONVERSE event indicates that a transaction is
          expecting a reply as a result of either an EXEC CICS RECEIVE command,
          or an EXEC CICS CONVERSE command.

          The application should issue a CICS_EpiReply call to return the data
          to CICS, as follows:

          o If the transaction has issued an EXEC CICS RECEIVE command without
            specifying the BUFFER option, the buffer might contain data sent
            from the transaction, or it might be empty. If there is data to
            process, you should deal with it before replying. The reply should
            be sent when the data to be sent is available.

          o If the transaction has issued an EXEC CICS RECEIVE BUFFER command,
            the data buffer contains the 3270 Read Buffer command and the Size
            field is set to 1. The reply should be sent immediately.

 Fields completed

          Event
                    The CICS_EPI_EVENT_CONVERSE event code.

          Data
                    A pointer to the buffer that is updated to contain the data
                    sent by the transaction, as defined above.

          Size
                    The length of the data in the buffer. This may be set to
                    zero to indicate that no data was sent, but a reply is
                    still expected.


ΓòÉΓòÉΓòÉ 8.6.3. CICS_EPI_EVENT_END_TRAN ΓòÉΓòÉΓòÉ

CICS_EPI_EVENT_END_TRAN

 Purpose

          The CICS_EPI_EVENT_END_TRAN event indicates the end of a transaction
          that was running against a terminal resource. If the transaction
          abended, it indicates the abend code; if the transaction completed
          normally, the AbendCode field is set to spaces. If the transaction
          was pseudoconversational, the TransId field contains the name of the
          next transaction required. The application should start this
          transaction by issuing a CICS_EpiStartTran call.

 Fields completed

          Event
                    The CICS_EPI_EVENT_END_TRAN event code.

          TransId
                    The name of the next transaction to start, if the previous
                    transaction was pseudoconversational. This name is 4
                    characters long and null-terminated. If there is no next
                    transaction, the field is set to nulls.

          AbendCode
                    The abend code, if the transaction abended. This code is 4
                    characters long and null-terminated. If the transaction
                    completed normally, the field is set to spaces.


ΓòÉΓòÉΓòÉ 8.6.4. CICS_EPI_EVENT_START_ATI ΓòÉΓòÉΓòÉ

CICS_EPI_EVENT_START_ATI

 Purpose

          The CICS_EPI_EVENT_START_ATI event indicates that an ATI transaction
          has been started against the terminal resource. If the terminal
          resource receives an ATI request while it is running another
          transaction, the request is held until the transaction ends. The
          transaction is then started on behalf of the terminal resource, and
          the CICS_EPI_EVENT_START_ATI event is generated to inform the
          application.

 Fields completed

          Event
                    The CICS_EPI_EVENT_START_ATI event code.

          TransId
                    The name of the transaction that was started. This name is
                    4 characters long and null-terminated.


ΓòÉΓòÉΓòÉ 8.6.5. CICS_EPI_EVENT_END_TERM ΓòÉΓòÉΓòÉ

CICS_EPI_EVENT_END_TERM

 Purpose

          The CICS_EPI_EVENT_END_TERM event indicates that a terminal resource
          no longer exists. After this event, the terminal index that was
          previously used for the terminal resource is not valid. If the EPI
          detects that a CICS server has shut down, CICS_EPI_EVENT_END_TERM
          events are generated for all terminal resources that the application
          has installed in that server and not subsequently deleted.

 Fields completed

          Event
                    The CICS_EPI_EVENT_END_TERM event code.

          EndReason
                    An indication of why the terminal resource was deleted. It
                    can be one of the following values:

             CICS_EPI_END_SIGNOFF
                       The terminal resource was signed off. This can be as a
                       result of running the CESF transaction or of calling the
                       CICS_EpiDelTerminal function.

             CICS_EPI_END_SHUTDOWN
                       The CICS server is shutting down.

             CICS_EPI_END_OUTSERVICE
                       The terminal resource has been switched out of service.

             CICS_EPI_END_UNKNOWN
                       An unexpected error has occurred.

             CICS_EPI_END_FAILED
                       An attempt to delete a terminal resource failed.

          AbendCode
                    A string specifying the abend code for the failure, if the
                    EndReason field is set to CICS_EPI_END_FAILED.


ΓòÉΓòÉΓòÉ 8.6.6. CICS_EPI_EVENT_HELP ΓòÉΓòÉΓòÉ

CICS_EPI_EVENT_HELP

     Note This event is presented only in the CICS on Open Systems environment.

 Purpose

          The CICS_EPI_EVENT_HELP event indicates that a transaction has
          requested that help information be displayed. It provides a text
          string indicating the topic corresponding to the help request. The
          application may be able to invoke an operating system help facility
          to display the help information.

 Fields completed

          Event
                    The CICS_EPI_EVENT_HELP event code.

          Data
                    A pointer to the buffer that is updated to contain a
                    null-terminated string describing the requested help topic.

          Size
                    The length of the help topic string, excluding the
                    terminating null.


ΓòÉΓòÉΓòÉ 8.7. 3270 data streams for the EPI ΓòÉΓòÉΓòÉ

The data streams implemented for the EPI follow those defined in the 3270 Data
Stream Programmer's Reference. All data flows for the EPI are in ASCII format,
and structured fields are not supported. Data flows are defined under the
following topics in the 3270 Data Stream Programmer's Reference:

 o Introduction to the 3270 data stream (excluding structured fields)
 o 3270 data stream commands
 o Character sets, orders and attributes
 o Keyboard and printer operations.
 The use of 3270 data streams within the EPI, and some nonstandard orders and
 attributes, are defined here.

 Except in the CICS on Open Systems environment, the supplied C header file
 CICS3270.H, COBOL copybook CICS3270.CBL, and PL/I include file CICS3270.INC
 contain constants and conversion tables that you will find useful in handling
 3270 data streams. (These files are not supplied in the CICS on Open Systems
 environment.)

 Note that if a CICS user transaction issues EXEC CICS SEND and EXEC CICS
 RECEIVE commands, CICS does not process the data (after the initial control
 bytes) that is passed between the EPI application and the CICS transaction. In
 this case, the data buffer may be used to pass user-specified data between the
 programs. Be aware that the contents of the data buffer may be code-page
 converted if the buffer is passed between CICS systems, in which case the data
 should be limited to ASCII and EBCDIC characters.

 If a CICS transaction issues EXEC CICS SEND MAP and EXEC CICS RECEIVE MAP
 commands, CICS converts the data from the BMS structure to a 3270 data stream.
 In this case, the application receives 3270 data from CICS and should return
 valid 3270 data to be converted for the transaction.


ΓòÉΓòÉΓòÉ 8.7.1. Inbound data streams (EPI to CICS) ΓòÉΓòÉΓòÉ

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé  AID   Γöé  Cursor  Γöé     Data buffer    Γöé
Γöé (1 byte) Γöé  address Γöé    (variable length)   Γöé
Γöé      Γöé (2 bytes)Γöé              Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

EPI applications send 3270 data to CICS on calls to the following functions:

 o CICS_EpiStartTran
 o CICS_EpiReply.

 The format in both cases is the same. The data stream must be a minimum of 3
 non-null bytes, representing the AID and cursor address; the sole exception to
 this is if the AID represents the CLEAR key or a PA key, when the data stream
 may consist of the AID only. These fields are passed to the CICS transaction
 in the EIBAID and EIBCPOSN fields of the EIB.

 The contents of the data buffer consist of:

 o ASCII displayable characters with embedded 3270 control characters, when it
   is passed to an EXEC CICS RECEIVE MAP command.

 o User-specified data, when it is passed to an EXEC CICS RECEIVE command.

 On starting a transaction, the transaction ID is extracted from the start of
 the data buffer as follows:

 o If a set buffer address (SBA) order is present at the start of the data
   buffer, the transaction ID is extracted from the 4th through 7th bytes of
   the buffer.

 o If an SBA is not present at the start of the data buffer, the transaction ID
   is extracted from the 1st through 4th bytes of the buffer.

 In either case, the transaction ID may be shorter than 4 bytes, being
 delimited by either another SBA, an ASCII space, or the end of the string.

 The contents of the data buffer passed on the start of a CICS transaction are
 available to the transaction in response to an initial EXEC CICS RECEIVE
 command.

 When the application replies, the contents of the data buffer are available in
 an unconverted form in response to an EXEC CICS RECEIVE command or converted
 to a BMS structure in response to an EXEC CICS RECEIVE MAP command.

 Note:  It is the EPI programmer's responsibility in the latter case to ensure
        that the data is formatted correctly so that the conversion succeeds.


ΓòÉΓòÉΓòÉ 8.7.2. Outbound data streams (CICS to EPI) ΓòÉΓòÉΓòÉ

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Command Γöé Write control Γöé    Data buffer    Γöé
Γöé (1 byte)Γöé  character  Γöé  (variable length)  Γöé
Γöé     Γöé  (1 byte)   Γöé            Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The 3270 commands are either write or read commands, instructing the EPI to
process the data or to reply with data respectively.

On a CICS_EPI_EVENT_SEND event, the command is one of the following 3270 write
commands:

 o Write
 o Erase/Write
 o Erase/Write Alternate
 o Erase All Unprotected.

 The first three commands are followed by a write control character (WCC) and
 data. An Erase All Unprotected command has neither WCC nor data. The Write
 Structured Field command is not generated by CICS and is therefore not
 supported for the EPI.

 The contents of the data buffer consist of:

 o ASCII displayable characters with embedded 3270 control characters, when it
   is passed from an EXEC CICS SEND MAP command.

 o User-specified data, when it is passed from an EXEC CICS SEND command.

 A CICS_EPI_EVENT_CONVERSE event specifies a read command. The contents of the
 data stream vary with the source of the event, as follows:

 o If the event is the result of an EXEC CICS RECEIVE command, the data buffer
   might contain data sent by the transaction, or it might be empty. The EPI
   program should reply when the data to be sent is available.

 o If the event is the result of an EXEC CICS RECEIVE BUFFER command, the data
   buffer contains the 3270 Read Buffer command. This should be processed as
   described in the 3270 Data Stream Programmer's Reference.

 The Read Modified and Read Modified All commands are not generated by CICS and
 are therefore not supported for the EPI.


ΓòÉΓòÉΓòÉ 8.7.3. 3270 order codes ΓòÉΓòÉΓòÉ

3270 orders are included in both inbound and outbound data streams to provide
additional control function. Order codes occurring in 3270 data streams lists
the order codes that may occur in 3270 data streams, and shows whether they
relate to inbound or outbound data streams, or both.

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Table 2. Order codes occurring in 3270 data streams              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Order code                   Γöé Inbound    Γöé Outbound   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Start field (SF)                Γöé Yes      Γöé Yes      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Start field extended (SFE)           Γöé Yes      Γöé Yes      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Set buffer address (SBA)            Γöé Yes      Γöé Yes      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Set attribute (SA)               Γöé Yes      Γöé Yes      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Modify field (MF)               Γöé No       Γöé Yes      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Insert cursor (IC)               Γöé No       Γöé Yes      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Program tab (TB)                Γöé No       Γöé Yes      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Repeat to address (RA)             Γöé No       Γöé Yes      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Erase unprotected to address (EUA)       Γöé No       Γöé Yes      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Graphic escape (GE)              Γöé No       Γöé No      Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Note:  The 3270 Data Stream Programmer's Reference states that the SFE, SA, and
       MF orders are not supported in ASCII. However, they do occur in 3270
       data streams for the EPI, where they take the following values:

              SFE     X'10'
              SA      X'1F'
              MF      X'1A'

MF was formerly assigned the value X'1E'. However the Field Mark format control
order is assigned the same value. Without the change to X'1A', an EPI
application would be unable to distinguish between MF and FM.

Each of these orders is followed by one or more attribute type-value pairs. The
count of attribute pairs and the attribute type are both binary values, and are
thus as defined in the 3270 Data Stream Programmer's Reference. However, the
contents of the attribute value field may vary from those defined in the 3270
Data Stream Programmer's Reference as follows:

 o If the attribute type is less than or equal to X'C0' (for example, a color),
   the attribute value is defined as an EBCDIC value in the 3270 Data Stream
   Programmer's Reference. The EPI uses the ASCII equivalent of the EBCDIC
   value; for example, red is defined as X'F2' in the 3270 Data Stream
   Programmer's Reference, and should be defined as X'32' in the EPI data
   stream.

 o If the attribute type is greater than X'C0' (for example, field outlining),
   the attribute value is a binary value. The EPI uses the values defined in
   the 3270 Data Stream Programmer's Reference.

 Further details of 3270 orders and other control characters are supplied in
 the files named in the following table.

  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  Γöé             Γöé CICS for AIX Version 2.1 Γöé Other environments    Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé COBOL copybook      Γöé N/A            Γöé CICS3270.CBL       Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé C header file      Γöé cics3270.h        Γöé CICS3270.H        Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé PL/I include file    Γöé N/A            Γöé CICS3270.INC       Γöé
  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 In the CICS on Open Systems environment, 3270 support files are not available
 before CICS for AIX Version 2.1.


ΓòÉΓòÉΓòÉ 8.8. Microsoft Windows considerations ΓòÉΓòÉΓòÉ

     Note The following information applies only to the IBM CICS Client for
     Windows.

 The CICS_EpiInitialize function has two additional parameters:

 hWnd
           The handle of the Microsoft Windows window to which EPI messages
           will be posted.

 MsgId
           The message identifier to be used for posting EPI messages to the
           window specified in the hWnd parameter.

 The EPI application is posted a Windows message (using the hWnd and MsgId
 values) in any of the following situations:

 o The CICS_EpiInitialize call has completed.

 o The CICS_EpiAddTerminal call has completed.

 o An incoming event for a terminal resource has been received.
   (CICS_EpiGetEvent should be called to receive the event data.)

 Values are assigned to the wParam and lParam parameters within these messages
 as follows. In the case of lParam, the LOWORD of this parameter is used.

 wParam

    CICS_EPI_WIN_INITIALIZED
              CICS_EpiInitialize complete

    CICS_EPI_WIN_INSTALLED
              CICS_EpiAddTerminal complete

    CICS_EPI_WIN_EVENT
              An incoming terminal event

 lParam

    X'0000'
              CICS_EpiInitialize has completed.

    Terminal index
              Index number of the terminal resource installed by a successful
              CICS_EpiAddTerminal, or of the terminal resource to which an
              incoming event belongs.

    X'FFFF'
              CICS_EpiAddTerminal has completed, but terminal resource
              installation failed.

 After receiving a message with wParam set to CICS_EPI_WIN_INITIALIZED, the
 application should call CICS_EpiGetSysError to check for any install errors.

 If lParam is set to X'FFFF', CICS_EpiGetSysError should be called with the
 TermIndex parameter set to CICS_EPI_TERM_INDEX_NONE. (A terminal index will
 not have been allocated if the terminal resource install failed.)

 If lParam is not set to X'FFFF', CICS_EpiGetSysError should be called with the
 TermIndex parameter set to the lParam value.

 Under Microsoft Windows, the EPI functions CICS_EpiInitialize and
 CICS_EpiAddTerminal are asynchronous (all other functions are synchronous).
 This means that the application should wait for a message to be posted before
 continuing after each of these two calls.


ΓòÉΓòÉΓòÉ 9. Creating ECI and EPI application programs ΓòÉΓòÉΓòÉ

This chapter contains language-dependent information about the external access
interfaces, and is organized as follows:

 Writing the non-CICS applications
 Making ECI calls
 Making EPI calls
 Compiling and linking applications

 This chapter does not deal with testing or debugging ECI and EPI applications.
 You should refer to the programming manuals for the environment in which you
 are working. These are listed in the Related publications section of the
 preface of this book.


ΓòÉΓòÉΓòÉ 9.1. Writing the non-CICS applications ΓòÉΓòÉΓòÉ

ECI and EPI applications are standard stand-alone programs that can be run on
any of the client systems, and can use the server implementations of the ECI
and EPI on CICS for OS/2 and CICS for Windows NT servers. Programs that do not
make operating-system-specific calls are portable between these environments.
The sample programs and associated build files for your environment illustrate
much of what is discussed here.

An application program may use the facilities of both ECI and EPI.

Applications may be written in C (or C++), COBOL, or PL/I, though not all these
languages are available in every environment.

The following table shows for each programming environment

 o the names of the C header file, COBOL copybook, or PL/I include file for the
   ECI

 o the names of the C header file, COBOL copybook, or PL/I include file for the
   EPI

 o the names of the type definition files for either interface for C and PL/I
   programs. (Type definition files are not used with COBOL.)

 The entry N/A in the table indicates that the combination of language and
 interface are not supported.

  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  Γöé Use           Γöé CICS on Open Systems   Γöé Other environments    Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé ECI: C programs     Γöé cics_eci.h        Γöé CICS_ECI.H        Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé ECI: COBOL programs   Γöé CICS-ECI         Γöé CICSECI.CBL       Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé ECI: PL/I programs    Γöé cics_eci.inc (AIX only)  Γöé CICS_ECI.INC       Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé EPI: C programs     Γöé cics_epi.h        Γöé CICS_EPI.H        Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé EPI: COBOL programs   Γöé N/A            Γöé CICSEPI.CBL       Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé EPI: PL/I programs    Γöé N/A            Γöé CICS_EPI.INC       Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé Type definitions: C   Γöé cicstype.h        Γöé CICSTYPE.H        Γöé
  Γöé programs         Γöé              Γöé             Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé Type definitions: PL/I  Γöé cicstype.inc       Γöé CICSTYPE.INC       Γöé
  Γöé programs         Γöé              Γöé             Γöé
  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 You should study the contents of the file appropriate to the language you
 intend to use. Each file contains the definitions of all the entry points,
 types, data structures, and constants needed for writing programs for the
 corresponding interface.

 The naming conventions for the structures, fields, and constants of the
 interfaces in the different languages are as follows:

 o PL/I and C-the names are the same as the names used earlier in this book to
   describe the interfaces.

 o COBOL-the names are upper-case versions of the names used earlier in this
   book to describe the interfaces with hyphens instead of underscores.

 There are a few exceptions to this convention, and these are noted where they
 occur.

 When compiling C programs, you may need to ensure that the structures passed
 to the CICS external facilities are packed. If this is necessary, the C header
 files will contain the #pragma pack directive, which should not be changed.


ΓòÉΓòÉΓòÉ 9.2. Making ECI calls ΓòÉΓòÉΓòÉ

ECI functions are called in the manner described below.

COBOL applications must ensure that the ECI function calls are statically
linked at link time by using the system linkage convention.

 o For IBM VisualAge for COBOL for OS/2, you should use the default
   CALLINTERFACE(System) linkage.

 o For Micro Focus Object COBOL, you should use call-convention 8 for every
   program call, or use the default call-convention 0 and compile using the
   LITLINK compiler directive.


ΓòÉΓòÉΓòÉ 9.2.1. CICS_ExternalCall ΓòÉΓòÉΓòÉ

The method of calling CICS_ExternalCall is shown here for COBOL, C, and for
PL/I. The ECI parameter block (ECI-PARMS for COBOL, ECI_PARMS for C, and
ECI_PARMS for PL/I) is used for passing parameters to the ECI. The format of
the call and associated declarations is as follows:


ΓòÉΓòÉΓòÉ 9.2.1.1. For C programs: ΓòÉΓòÉΓòÉ

  ECI_PARMS      EciBlock;
  cics_ushort_t  Response;
  .
  .
  .
  Response = CICS_ExternalCall(&EciBlock);


ΓòÉΓòÉΓòÉ 9.2.1.2. For COBOL programs: ΓòÉΓòÉΓòÉ

  CALL  'CICSEXTERNALCALL'
  USING BY REFERENCE ECI-PARMS
  RETURNING ECI-RETURN-CODE.

The name '_CICS_ExternalCall' may also be used with the Micro Focus Object
COBOL compiler, but it is not recommended.


ΓòÉΓòÉΓòÉ 9.2.1.3. For PL/I programs: ΓòÉΓòÉΓòÉ

  dcl Response fixed bin(15);
  dcl EciBlock type ECI_PARMS;
  .
  .
  .
  Response = CICS_ExternalCall(EciBlock);


ΓòÉΓòÉΓòÉ 9.2.1.4. For REXX programs: ΓòÉΓòÉΓòÉ

Before using CICS_ExternalCall, the REXX program must add the function for
CICS_ExternalCall to its environment as follows:

  Call RxFuncAdd 'CICS_ExternalCall', 'cclrxeci', 'RxCICS_ExternalCall'

Once the function has been added, the program may use it any number of times.

The format of the call is as follows:

  retcode = CICS_ExternalCall('ECI_PARMS.')

where ECI_PARMS is the name chosen for the REXX stem representing the ECI
parameter block. Do not omit the period at the end of the name, or the single
quotation marks surrounding it.

The values for eci_call_type, eci_extend_mode, and eci_version in the ECI
parameter block, and for ConnectionType, CicsServerStatus, and CicsClientStatus
in the ECI status block are character literals that match the names used
earlier in this book. The following sample assignment statement shows how,
having chosen ECI_PARMS as the stem name, the eci_call_type field in the ECI
parameter block is set to ECI_SYNC.

ECI_PARMS.eci_call_type = 'ECI_SYNC'

The return code values ECI_NO_ERROR, and so on, are defined in the file
RXECI.MSG supplied with the samples.


ΓòÉΓòÉΓòÉ 9.2.2. Callback routines ΓòÉΓòÉΓòÉ

Each callback routine has only one parameter. You should consult the sample
programs for examples of writing callback routines.


ΓòÉΓòÉΓòÉ 9.2.3. CICS_EciListSystems ΓòÉΓòÉΓòÉ

The format of the call in the different programming languages is as follows:


ΓòÉΓòÉΓòÉ 9.2.3.1. For C programs: ΓòÉΓòÉΓòÉ

  #define MAX_SYS 5
  cics_sshort_t    Response;
  cics_ushort_t    Count;
  CICS_EciSystem_t List[MAX_SYS];
  .
  Count = MAX_SYS;
  .
  Response = CICS_EciListSystems(NULL, &Count, List);


ΓòÉΓòÉΓòÉ 9.2.3.2. For COBOL programs: ΓòÉΓòÉΓòÉ

The COBOL name of the system information structure is CICS-ECISYSTEM, which is
contrary to the naming convention stated earlier. In the CICS on Open Systems
environment, the array of CICS-ECISYSTEM structures is made part of
CICS-ECISYSARRAY to comply with the requirements of the ANSI standard for
COBOL. However the array can still be referred to using the name
CICS-ECISYSTEM, as shown in the example below.

  01 LIST-SIZE PIC 9(4) COMP-5.

  CALL 'CICSECILISTSYSTEMS'
  USING
    BY REFERENCE NULL-PTR
    BY REFERENCE LIST-SIZE
    BY REFERENCE CICS-ECISYSTEM
  RETURNING ECI-RETURN-CODE.

The name '_CICS_EciListSystems' may also be used with the Micro Focus Object
COBOL compiler, but it is not recommended.


ΓòÉΓòÉΓòÉ 9.2.3.3. For PL/I programs: ΓòÉΓòÉΓòÉ

  dcl EciRetCode fixed bin(15);
  dcl count fixed bin(15);
  dcl list type CICS_EciSystem_t;
  .
  .
  .
  EciRetCode = CICS_EciListSystems(null(), count, list);


ΓòÉΓòÉΓòÉ 9.2.3.4. For REXX programs: ΓòÉΓòÉΓòÉ

Before using CICS_EciListSystems, the REXX program must add the function for
CICS_EciListSystems to its environment as follows:

  Call RxFuncAdd 'CICS_EciListSystems', 'cclrxeci', 'RxCICS_EciListSystems'

Once the function has been added, the program may use it any number of times.

The format of the call is as follows:

  retcode = CICS_EciListSystems(, 'count', 'LIST.')

No parameter need be supplied for NameSpace, count is the name of the REXX
variable chosen for Systems, and LIST is the name chosen for the REXX stem
representing List. Do not omit the period at the end of the name, or the single
quotation marks surrounding it.

On return from the call, the names LIST.1.SystemName, and LIST.1.Description,
are used to refer to the fields in the first array element, and so on.


ΓòÉΓòÉΓòÉ 9.2.4. Debugging with REXX ΓòÉΓòÉΓòÉ

Special debugging facilities are provided for ECI applications using REXX.

Setting the REXX variable DEBUG to any non-zero value will cause debug
information to be sent to a log file. The path name of the file can be
specified in the REXX variable DEBUGFILE, and the default is the file
CCLRXECI.LOG in the directory where CCLRXECI.DLL is executing. If the file
exists already, debug information is appended to it.


ΓòÉΓòÉΓòÉ 9.3. Making EPI calls ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 9.3.1. EPI functions ΓòÉΓòÉΓòÉ

EPI functions are called in a standard manner. Examples of calling the
CICS_EpiListSystems function follow.

COBOL applications must ensure that the EPI function calls are statically
linked at link time by using the system linkage convention.

 o For IBM VisualAge for COBOL for OS/2, you should use the default
   CALLINTERFACE(System) linkage.

 o For Micro Focus Object COBOL, you should use call-convention 8 for every
   program call, or use the default call-convention 0 and compile using the
   LITLINK compiler directive.


ΓòÉΓòÉΓòÉ 9.3.1.1. For C programs: ΓòÉΓòÉΓòÉ

  #define MAX_SYS 5
  CICS_EpiSystem_t System;
  cics_ushort-t    Count;
  cics_sshort_t    Response;
  .
  Count = MAX_SYS;
  .
  Response = CICS_EpiListSystems(NULL, &Count, &System);


ΓòÉΓòÉΓòÉ 9.3.1.2. For COBOL programs: ΓòÉΓòÉΓòÉ

Except in the CICS on Open Systems environment, in which EPI calls from COBOL
are not supported, the following may be used:

  01 COUNT      PIC 9(4)  COMP-5.
  01 NAMESPACE  POINTER.
  .
  .
  .
  CALL 'CICSEPILISTSYSTEMS'
    USING BY VALUE NAMESPACE
      BY REFERENCE COUNT
      BY REFERENCE CICS-EPISYSTEM
    RETURNING EPI-RETURN-CODE.


ΓòÉΓòÉΓòÉ 9.3.1.3. For PL/I programs: ΓòÉΓòÉΓòÉ

Except in the CICS on Open Systems environment, in which EPI calls from PL/I
are not supported, the following may be used:

  dcl System type CICS_EpiSystem_t,
      Count fixed bin(15),
      Response fixed bin(15);
  .
  .
  .
  Response = CICS_EpiListSystems(null(), Count, System);


ΓòÉΓòÉΓòÉ 9.3.1.4. For REXX programs: ΓòÉΓòÉΓòÉ

EPI functions are not available in REXX.


ΓòÉΓòÉΓòÉ 9.3.2. Callback routines ΓòÉΓòÉΓòÉ

Each callback routine has only one parameter. You should consult the sample
programs for examples of writing callback routines.


ΓòÉΓòÉΓòÉ 9.4. Compiling and linking applications ΓòÉΓòÉΓòÉ

This section gives some examples showing how to compile and link typical ECI
and EPI applications in the various client environments. These are examples
only, and may refer to specific compilers and linkers.

You should refer to the samples supplied with your environment for more
information about compiling and linking programs.


ΓòÉΓòÉΓòÉ 9.4.1. IBM CICS Client for DOS ΓòÉΓòÉΓòÉ

For examples of programs that call the ECI and EPI, refer to the samples
supplied with the client in the following libraries:

 o \CICSCLI\SAMPLES\C
 o \CICSCLI\SAMPLES\COBOL


ΓòÉΓòÉΓòÉ 9.4.1.1. For C programs: ΓòÉΓòÉΓòÉ

  cl /c /DCICS_DOS program.c

  link program.obj,,,ccldos.lib;

Notes:

 o Example compiler used is Microsoft C Optimizing Compiler Version 6.00A.

 o The constant CICS_DOS must be defined to the compiler using the /DCICS_DOS
   option.

 o Programs may use any of the standard memory models.

 o The application must be linked with the CCLDOS.LIB library in addition to
   the standard C runtime libraries.

 o Callback functions are not supported in DOS.


ΓòÉΓòÉΓòÉ 9.4.1.2. For COBOL programs: ΓòÉΓòÉΓòÉ

  cobol program,,,,

  link program.obj,,,lcobol.lib+cobapi.lib+ccldos.lib;

Notes:

 o Example compiler used is Micro Focus COBOL Version 3.0.

 o Programs should use the LARGE memory model.

 o ECI and EPI function calls should be linked using call-convention 8.

 o The application must be linked with the CCLDOS.LIB library and must use the
   COBOL static link libraries.

 o Callback functions are not supported in DOS or COBOL.


ΓòÉΓòÉΓòÉ 9.4.2. IBM CICS Client for Windows ΓòÉΓòÉΓòÉ

For examples of programs that call the ECI and EPI, refer to the samples
supplied with the client in the following library:

 o \CICSCLI\SAMPLES\C


ΓòÉΓòÉΓòÉ 9.4.2.1. For C programs: ΓòÉΓòÉΓòÉ

  cl /c /Gsw /DCICS_WIN program.c

  link program.obj,,,cclwin.lib,program.def

Notes:

 o Example compiler used is Microsoft C/C++ Optimizing Compiler Version 7.00.

 o The constant CICS_WIN must be defined to the compiler using the /DCICS_WIN
   option.

 o The /Gsw options are recommended for compiling Windows programs.

 o Programs may use any of the standard memory models.

 o The application must be linked with the CCLWIN.LIB library in addition to
   the standard C runtime and Windows libraries.

 o A STACKSIZE of at least 8K is recommended in the linker .DEF file.

 o Callback functions must be declared using the CICSEXIT calling convention
   and must be created using the Windows function MakeProcInstance()-see
   samples for details.

 o The Windows resource compiler will also be required to create a functional
   Windows program, as normal.


ΓòÉΓòÉΓòÉ 9.4.3. IBM CICS Client for OS/2 ΓòÉΓòÉΓòÉ

For examples of programs that call the ECI and EPI, refer to the samples
supplied with the client in the following libraries:

 o \CICSCLI\SAMPLES\C
 o \CICSCLI\SAMPLES\COBOL
 o \CICSCLI\SAMPLES\PLI


ΓòÉΓòÉΓòÉ 9.4.3.1. For 32-bit C programs: ΓòÉΓòÉΓòÉ

  icc /C /Gt+ /DCICS_OS2 program.c

  link386 program.obj,,,cclos232.lib,program.def

Notes:

 o Example compiler used is IBM C/Set++.

 o The constant CICS_OS2 must be defined to the compiler using the /DCICS_OS2
   option.

 o The /Gt+ options is recommended to ensure any data items passed to the ECI
   or EPI do not span a 64K boundary.

 o The application must be linked with the CCLOS232.LIB library (since it is a
   32-bit application) in addition to the standard C runtime and OS/2
   libraries.

 o A STACKSIZE of at least 16K is recommended in the linker .DEF file.

 o Callback functions must be declared using the CICSEXIT calling
   convention-see samples for details.


ΓòÉΓòÉΓòÉ 9.4.3.2. For 16-bit C programs: ΓòÉΓòÉΓòÉ

  cl /c /Gs /DCICS_OS2 program.c

  link program.obj,,,cclos2.lib,program.def

Notes:

 o Example compiler used is Microsoft C Optimizing Compiler Version 6.00A.

 o The constant CICS_OS2 must be defined to the compiler using the /DCICS_OS2
   option.

 o The /Gs option is recommended if callback functions are to be used.

 o The application must be linked with the CCLOS2.LIB library (since it is a
   16-bit application) in addition to the standard C runtime and OS/2
   libraries.

 o A STACKSIZE of at least 16K is recommended in the linker .DEF file.

 o Callback functions must be declared using the CICSEXIT calling
   convention-see samples for details.


ΓòÉΓòÉΓòÉ 9.4.3.3. For 32-bit COBOL programs: ΓòÉΓòÉΓòÉ

If you are using IBM VisualAge for COBOL for OS/2:

  cob2 -c -qapost -qnosequence -qlib. prog.cbl

  ilink /NOFREE /NOD /NOI /MAP prog.obj,,,OS2386 iwzrlib cclos232,prog.def

If you are using Micro Focus Object COBOL:

  cobol prog.cbl;

  cblnames -mPROG -oPROG.CBJ prog

  link386 /NOD /NOI prog.obj prog.cbj,,,OS2386 mfrts32 cclos232,prog.def

Notes:

 o You must resolve ECI and EPI function calls at link time using the system
   linkage convention. This is the default linkage for IBM VisualAge for COBOL
   for OS/2. If you use Micro Focus Object COBOL, you must use call-convention
   8 on all ECI and EPI functions, or use the default call-convention 0 and
   compile using the LITLINK compiler directive.


ΓòÉΓòÉΓòÉ 9.4.3.4. For 16-bit COBOL programs: ΓòÉΓòÉΓòÉ

  cobol program,,,,

  link program.obj,,,coblib.lib+cclos2.lib,program.def

Notes:

 o Example compiler used is Micro Focus COBOL Version 3.0.

 o Programs should use the LARGE memory model.

 o Programs must be compiled with the LITLINK compiler directive.

 o The application must be linked with the CCLOS2.LIB library (since it is a
   16-bit application) and may use either the COBOL static or dynamic link
   libraries.

 o A STACKSIZE of at least 16K is recommended in the linker .DEF file.

 o Callback functions are not supported in COBOL.


ΓòÉΓòÉΓòÉ 9.4.3.5. For PL/I programs: ΓòÉΓòÉΓòÉ

  pli program

  link386 program.obj,,,cclos232.lib,program.def

Notes:

 o Example compiler used is IBM PL/I for OS/2 Version 1 Release 1.

 o The application must be linked with the CCLOS232.LIB library (since it is a
   32-bit application) in addition to the standard PL/I runtime and OS/2
   libraries.

 o A STACKSIZE of at least 16K is recommended in the linker .DEF file.

 o Callback functions must be declared using the CICSEXIT calling
   convention-see samples for details.


ΓòÉΓòÉΓòÉ 9.4.4. IBM CICS Client for Macintosh ΓòÉΓòÉΓòÉ

For examples of programs that call the ECI and EPI, refer to the samples
supplied with the client in the following library:

 o :CICSCLI:SAMPLES:C


ΓòÉΓòÉΓòÉ 9.4.4.1. For C programs: ΓòÉΓòÉΓòÉ

  C program.c -o program.c.o -model far -i 'HD:cicscli:headers:' -d CICS_MAC

  Link -o program program.c.o 'HD:cicscli:lib:'cclmac.cl.o
                              "HD:MPW:Libraries:Libraries:"Runtime.o
                              "HD:MPW:Libraries:Libraries:"Interface.o
                              "HD:MPW:Libraries:CLibraries:"StdCLib.o
                              "HD:MPW:Libraries:Libraries:"LibraryManager.o
                              -model far

  SetFile program -t APPL -c 'CIC1' -a B

Notes:

 o Example compiler used is MPW C Version 3.3.

 o The constant CICS_MAC must be defined to the compiler using the -d CICS_MAC
   option.

 o The program must be linked with LibraryManager.o for access to the shared
   library.

 o The creator types used in the samples on the `SetFile' line (CIC1 and CIC2)
   match the resource file provided. The CICS Client for Macintosh product has
   registered with Apple the creator types CICS, CICE, CICP, and CICX for use
   within this product. You must not use these names for your own programs.

 o Callback functions must be declared using the CICSEXIT calling
   convention-see samples for details.


ΓòÉΓòÉΓòÉ 9.4.5. CICS for OS/2 Version 2.0.1 server implementation ΓòÉΓòÉΓòÉ

For examples of programs that call the ECI and EPI, refer to the samples
supplied with the CICS product. CICS for OS/2 V2.0.1 provides C, COBOL, and
PL/I source and makefile samples in the following directories:

 o \CICS200\SAMPLES\C\SOURCE
 o \CICS200\SAMPLES\COBOL\SOURCE
 o \CICS200\SAMPLES\PLI\SOURCE


ΓòÉΓòÉΓòÉ 9.4.5.1. For 32-bit C programs: ΓòÉΓòÉΓòÉ

  icc /Gt+ prog.c faacic32.lib

Notes:

 o ECI applications are created as shown above.
 o To create EPI applications you should use FAACLIB.LIB instead of
   FAACIC32.LIB.


ΓòÉΓòÉΓòÉ 9.4.5.2. For 16-bit C programs: ΓòÉΓòÉΓòÉ

  cl prog.c /Gs /link /stack:16384 faaclib


ΓòÉΓòÉΓòÉ 9.4.5.3. For COBOL programs: ΓòÉΓòÉΓòÉ

  cobol prog.cbl /CASE

  link /NOD prog,,,coblib+faaclib


ΓòÉΓòÉΓòÉ 9.4.5.4. For PL/I programs: ΓòÉΓòÉΓòÉ

  pli prog.pli ( tiled

  link386 /NOD / NOI prog,,,faacic32 ibmlink ceelink os2386

Notes:

 o ECI applications are created as shown above.
 o To create EPI applications you should use FAACLIB.LIB instead of
   FAACIC32.LIB.


ΓòÉΓòÉΓòÉ 9.4.6. CICS for OS/2 Version 3 server implementation ΓòÉΓòÉΓòÉ

For examples of programs that call the ECI and EPI, refer to the samples
supplied with the CICS product. CICS for OS/2 V3.0 provides C, COBOL, and PL/I
source and makefile samples in the following directories:

 o \CICS300\TOOLS\C\SAMPLES\SOURCE
 o \CICS300\TOOLS\COBOL\SAMPLES\SOURCE
 o \CICS300\TOOLS\PLI\SAMPLES\SOURCE


ΓòÉΓòÉΓòÉ 9.4.6.1. For 32-bit C programs: ΓòÉΓòÉΓòÉ

  icc /Gt+ prog.c faacic32.lib


ΓòÉΓòÉΓòÉ 9.4.6.2. For 16-bit C programs: ΓòÉΓòÉΓòÉ

  cl prog.c /Gs /link /stack:16384 faaclib


ΓòÉΓòÉΓòÉ 9.4.6.3. For COBOL programs: ΓòÉΓòÉΓòÉ

If you are using IBM VisualAge for COBOL for OS/2:

  cob2 -c -qapost -qnosequence -qlib. prog.cbl

  ilink /NOFREE /NOD /NOI /MAP prog.obj,,,OS2386 iwzrlib cclos232,prog.def

If you are using Micro Focus Object COBOL:

  cobol prog.cbl;

  cblnames -mPROG -oPROG.CBJ prog

  link386 /NOD /NOI prog.obj prog.cbj,,,OS2386 mfrts32 cclos232,prog.def

Note:

 o You must resolve ECI and EPI function calls at link time using the system
   linkage convention. This is the default linkage for IBM VisualAge for COBOL
   for OS/2. If you use Micro Focus Object COBOL, you must use call-convention
   8 on all ECI and EPI functions, or use the default call-convention 0 and
   compile using the LITLINK compiler directive.


ΓòÉΓòÉΓòÉ 9.4.6.4. For PL/I programs: ΓòÉΓòÉΓòÉ

  pli prog.pli ( tiled

  link386 /NOD / NOI prog,,,faacic32 ibmlink ceelink os2386


ΓòÉΓòÉΓòÉ 9.4.7. CICS for Windows NT server implementation ΓòÉΓòÉΓòÉ

For examples of programs that call the ECI and EPI, refer to the samples
supplied with the CICS product. CICS for Windows NT V2.0 provides C and COBOL
source and makefile samples in the following directories:

 o \CNT200\SAMPLES\C\SOURCE
 o \CNT200\SAMPLES\COBOL\SOURCE


ΓòÉΓòÉΓòÉ 9.4.7.1. For C programs: ΓòÉΓòÉΓòÉ

  cl prog.c faacicnt.lib


ΓòÉΓòÉΓòÉ 9.4.7.2. For COBOL programs: ΓòÉΓòÉΓòÉ

  cobol prog.cbl;

  cblnames -mPROG -oPRG.CBJ PROG.OBJ

  link prog.obj prog.cbj faacicnt.lib mfrts32.lib

Note:

 o ECI and EPI function calls should be resolved at link time using the system
   linkage convention. All ECI and EPI function calls should be made using
   call-convention 8. If the default call-convention 0 is used, then the COBOL
   application should be compiled using the LITLINK compiler directive.


ΓòÉΓòÉΓòÉ 9.4.8. CICS on Open Systems Clients ΓòÉΓòÉΓòÉ

For examples of programs that call the EPI, refer to the samples supplied with
the CICS product. Source code and makefiles are located in the following
directories:

 o IBM AIX client-/usr/lpp/cics/src/samples/epi
 o Other clients-/opt/cics/src/samples/epi

 To build the sample programs and transactions:

    make all

 To build the client side only programs:

    make client

 To install the transactions:

    make install

 To remove the built applications and transactions:

    make clean

 Notes:

 o The region name DEFAULT should be replaced with the target region in the
   makefile.

 o Refer to the program description in the leading comment block in the sample
   programs for details of operation.

 o When compiling ECI and EPI application programs with Micro Focus COBOL, you
   are recommended to use the NLS complier directive, so that the locale of the
   server is taken from the LANG environment variable.


ΓòÉΓòÉΓòÉ 10. ECI extensions that are environment-dependent ΓòÉΓòÉΓòÉ

This chapter describes extensions to the ECI that are supported in certain
environments. They are not part of CICS Family Client/Server Programming.

The chapter is organized as follows:

 Call type extensions
 Time-outs
 Fields to support ECI extensions
 Reply message formats
 ECI return notification
 Summary of input parameter requirements.


ΓòÉΓòÉΓòÉ 10.1. Call type extensions ΓòÉΓòÉΓòÉ

The following call types are for asynchronous calls.

For more information about the program link calls, study CICS_ExternalCall
return codes - environment-dependent extensions in conjunction with ECI_ASYNC.

For more information about the status information calls, study
CICS_ExternalCall return codes - environment-dependent extensions in
conjunction with ECI_STATE_ASYNC.


ΓòÉΓòÉΓòÉ 10.1.1. Asynchronous program link call, with notification by message (ECI_ASYNC_NOTIFY_MSG) ΓòÉΓòÉΓòÉ

This call type is available only for programs running under OS/2 Presentation
Manager, Microsoft Windows, or Windows NT.

The calling application gets control back when the ECI accepts the request.
Note that this does not indicate that the program has started to run, merely
that the parameters have been validated. The request might be queued for later
processing.

The ECI sends a notification message to the specified window when the response
is available. (For details of the message format, see Reply message formats.)
On receipt of this notification, the calling application should use
ECI_GET_REPLY or ECI_GET_SPECIFIC_REPLY to receive the actual response.

The following fields are required parameters for notification by message:

 o Either eci_async_notify.window_handle (for OS/2 Presentation Manager or
   Windows NT environment) or eci_async_notify.win_fields.hwnd (for Microsoft
   Windows environment) identifies the window to be notified.

 o eci_async_notify.win_fields.hinstance (for Microsoft Windows environment)
   indicates the hInstance of the calling program.

 o eci_message_id indicates the message type to be used in the notification
   process.

 eci_message_qualifier can be used as an input to provide a user-defined name
 for the call. It is returned as part of the notification message for the OS/2
 Presentation Manager and Windows NT environments.


ΓòÉΓòÉΓòÉ 10.1.2. Asynchronous program link call, with notification by semaphore (ECI_ASYNC_NOTIFY_SEM) ΓòÉΓòÉΓòÉ

This call type is available only for programs running under OS/2 or Windows NT.

The calling application gets control back when the ECI accepts the request.
Note that this does not indicate that the program has started to run, merely
that the parameters have been validated. The request might be queued for later
processing.

The ECI posts the specified semaphore when the response is available. On
receipt of this notification, the calling application should use ECI_GET_REPLY
or ECI_GET_SPECIFIC_REPLY to receive the actual response.

eci_message_qualifier can be used as an input to provide a user-defined name
for the call.

The following field is a required parameter for notification by semaphore:

 o eci_async_notify.sem_handle refers to the semaphore.


ΓòÉΓòÉΓòÉ 10.1.3. Asynchronous status call, with notification by message (ECI_STATE_ASYNC_MSG) ΓòÉΓòÉΓòÉ

This call type is available only for programs running under OS/2 Presentation
Manager, Microsoft Windows, or Windows NT.

eci_message_qualifier can be used as an input to provide a user-defined name
for the call.

The ECI sends a notification message to the specified window when the response
is available. (For details of the message format, see Reply message formats.)
On receipt of this notification, the calling application should use
ECI_GET_REPLY or ECI_GET_SPECIFIC_REPLY to receive the actual response.

For details of the additional parameters relating to notification by message,
see the description of the ECI_ASYNC_NOTIFY_MSG call type.


ΓòÉΓòÉΓòÉ 10.1.4. Asynchronous status call, with notification by semaphore (ECI_STATE_ASYNC_SEM) ΓòÉΓòÉΓòÉ

This call type is available only for programs running under OS/2 or Windows NT.

eci_message_qualifier can be used as an input to provide a user-defined name
for the call.

The ECI posts the specified semaphore when the response is available. On
receipt of this notification, the calling application should use ECI_GET_REPLY
or ECI_GET_SPECIFIC_REPLY to receive the actual response.

The following field is a required parameter for notification by semaphore:

 o eci_async_notify.sem_handle refers to the semaphore.


ΓòÉΓòÉΓòÉ 10.2. Time-outs ΓòÉΓòÉΓòÉ

Time-out support is provided in the ECI for the migration of programs from
CICS/OS2 local clients, and the use of time-out facilities is not recommended
in other environments. It could be used in a single-threaded environment, such
as DOS, to terminate very long synchronous calls, but the results are sometimes
unpredictable, as explained below.

The support consists of a field eci_timeout in the ECI parameter block, and two
return codes: ECI_ERR_RESPONSE_TIMEOUT and ECI_ERR_REQUEST_TIMEOUT.

In the processing of timeouts, there are two cases to consider.

 o The time-out occurs before the request has been forwarded to the server. In
   this case the response is ECI_ERR_REQUEST_TIMEOUT. The requested program was
   not called, and no server resources have been updated. If the call was
   intended to start, or be the whole of, a new logical unit of work, the
   logical unit of work was not started, and no recoverable resources have been
   updated. If the call was intended to continue an existing logical unit of
   work, the logical unit of work was continued, but no recoverable resources
   were updated, and the logical unit of work is still uncommitted. If the call
   was intended to end an existing logical unit of work, the logical unit of
   work was continued, no recoverable resources were updated, and the logical
   unit of work is still uncommitted.

 o The time-out occurs after the request has been forwarded to the server. In
   this case the response is ECI_ERR_RESPONSE_TIMEOUT, and it could be returned
   to a synchronous call, or to an asynchronous call, or to the reply
   solicitation request that gets the reply to an asynchronous call.

    - If the call was intended to be the only call of a new logical unit of
      work, the logical unit of work was started, but it is not possible for
      the application to determine whether updates were performed, and whether
      they were committed or backed out.

    - If the call was intended to end an existing logical unit of work by using
      ECI_NO_EXTEND, the logical unit of work has ended, but it is not possible
      for the application to determine whether updates were performed, and
      whether they were committed or backed out.

    - If the call was intended to continue or to end an existing logical unit
      of work by using ECI_COMMIT, the logical unit of work persists, and
      changes to recoverable resources are still pending.


ΓòÉΓòÉΓòÉ 10.3. Fields to support ECI extensions ΓòÉΓòÉΓòÉ

The following fields in the ECI parameter block are to support
environment-dependent extensions.

 eci_async_notify.window_handle
           (OS/2 and Windows NT environments, ECI_ASYNC_NOTIFY_MSG and
           ECI_STATE_ASYNC_MSG call types)

           The handle of the window to which the reply message will be posted.

           The ECI uses this field as input only.

           Note:  eci_window_handle is a synonym for this parameter.

 eci_async_notify.sem_handle
           (OS/2 and Windows NT environments, ECI_ASYNC_NOTIFY_SEM and
           ECI_STATE_ASYNC_SEM call types)

           A reference to an OS/2 semaphore. This semaphore is cleared when the
           asynchronous response is ready for collection.

    o 16-bit OS/2 applications should pass either a system semaphore handle or
      the address of a RAM semaphore.

    o 32-bit OS/2 applications should pass an event semaphore handle.

    o Windows NT applications should pass an event object handle.

           The ECI uses this field as input only.

 eci_async_notify.win_fields.hwnd
           (Microsoft Windows environment, ECI_ASYNC_NOTIFY_MSG and
           ECI_STATE_ASYNC_MSG call types)

           The handle of the Microsoft Windows window to which the reply
           message will be posted.

           The ECI uses this field as input only.

 eci_async_notify.win_fields.hinstance
           (Microsoft Windows environment, ECI_ASYNC_NOTIFY_MSG and
           ECI_STATE_ASYNC_MSG call types)

           The Microsoft Windows hInstance of the calling program as supplied
           during program initialization.

           The ECI uses this field as input only.

 eci_message_id
           (OS/2 Presentation Manager, Microsoft Windows, and Windows NT
           environments, ECI_ASYNC_NOTIFY_MSG and ECI_STATE_ASYNC_MSG call
           types)

           The message identifier to be used for posting the reply message to
           the window specified in the relevant window handle.

           The ECI uses this field as input only.

 eci_timeout
           (Program link calls and status calls only)

           An integer field specifying the maximum time in seconds that a
           request from the application is allowed to take. A timeout occurs if
           the servicing of a request takes longer than the specified time. The
           value must be in the range 0 through 32767. A value of zero means
           that the application sets no limit on the time to service a request.

           The ECI uses this field as input only.

 eci_extend_mode
           There is an additional value for program link calls in CICS OS/2
           Version 1.20- ECI_CANCEL. It has the same effect as ECI_COMMIT.


ΓòÉΓòÉΓòÉ 10.4. Reply message formats ΓòÉΓòÉΓòÉ

When an application makes an asynchronous call requesting notification by
message, the ECI returns the result in a message to a window using the
specified window handle and message identifier.

For OS/2 Presentation Manager, the message is divided into two parameters, as
follows: break all.

 MPARAM1

    High-order 16 bits
              Specified message qualifier

    Low-order 16 bits
              Return code

 MPARAM2   4-character abend code, if applicable

 For Microsoft Windows, the message is divided into two parameters, as follows:

 wParam
           Return code

 lParam
           4-character abend code, if applicable

 For Windows NT, the message is divided into two parameters, as follows: break
 all.

 wParam

    High-order 16 bits
              Specified message qualifier

    Low-order 16 bits
              Return code

 lParam    4-character abend code, if applicable


ΓòÉΓòÉΓòÉ 10.5. ECI return notification ΓòÉΓòÉΓòÉ

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Table 3. CICS_ExternalCall return codes - environment-dependent extensions  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Return code              Γöé Meaning                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ECI_ERR_NULL_WIN_HANDLE        Γöé An asynchronous call was specified  Γöé
Γöé                    Γöé with the window handle set to 0.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ECI_ERR_NULL_MESSAGE_ID        Γöé An asynchronous call was specified  Γöé
Γöé                    Γöé with the message identifier set to  Γöé
Γöé                    Γöé 0.                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ECI_ERR_NULL_SEM_HANDLE        Γöé A null semaphore handle was passed  Γöé
Γöé                    Γöé when a valid handle was required.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ECI_ERR_REQUEST_TIMEOUT        Γöé The time-out interval expired before Γöé
Γöé                    Γöé the request could be processed, or  Γöé
Γöé                    Γöé the specified interval was negative. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ECI_ERR_RESPONSE_TIMEOUT        Γöé The time-out interval expired while  Γöé
Γöé                    Γöé the program was running.       Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 10.6. Summary of input parameter requirements ΓòÉΓòÉΓòÉ

Input parameters for CICS_ExternalCall - environment-dependent extensions shows
the input parameters for an ECI call, and, for each call type, whether the
parameters are required (`R'), optional (`O'), or not applicable (`-'). Where a
parameter is shown as optional or not-applicable an initial field setting of
nulls is recommended. An asterisk (*) immediately following an `R' means that
further details regarding applicability are given under the description of the
parameter.

The following abbreviations are used in the Parameter column:

 AN        async_notify

 WF        win_fields

 Also, all named parameters have an eci_ prefix. Thus AN.WF.hwnd represents the
 eci_async_notify.win_fields.hwnd parameter.

 The following 3-character abbreviations are used for the call types in the
 column headings of the table:

 ANM       ECI_ASYNC_NOTIFY_MSG

 ANE       ECI_ASYNC_NOTIFY_SEM

 SAM       ECI_STATE_ASYNC_MSG

 SAE       ECI_STATE_ASYNC_SEM

  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  Γöé Table 4. Input parameters for CICS_ExternalCall - environment-dependent    Γöé
  Γöé      extensions                              Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé Parameter, eci_     Γöé   ANM   Γöé   ANE   Γöé   SAM   Γöé   SAE   Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé call_type        Γöé    R    Γöé    R   Γöé    R   Γöé    R   Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé program_name       Γöé    R*   Γöé   R*   Γöé    -   Γöé    -   Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé userid          Γöé    R    Γöé    R   Γöé    -   Γöé    -   Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé password         Γöé    R    Γöé    R   Γöé    -   Γöé    -   Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé transid         Γöé    O    Γöé    O   Γöé    -   Γöé    -   Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé commarea         Γöé    O    Γöé    O   Γöé   R*   Γöé   R*   Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé commarea_length     Γöé    O    Γöé    O   Γöé   R*   Γöé   R*   Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé timeout         Γöé    O    Γöé    O   Γöé    O   Γöé    O   Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé extend_mode       Γöé    R    Γöé    R   Γöé    R   Γöé    R   Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé AN.window_handle     Γöé    R*   Γöé    -   Γöé   R*   Γöé    -   Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé AN.sem_handle      Γöé    -    Γöé    R   Γöé    -   Γöé    R   Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé AN.WF.hwnd        Γöé    R*   Γöé    -   Γöé   R*   Γöé    -   Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé AN.WF.hinstance     Γöé    R*   Γöé    -   Γöé   R*   Γöé    -   Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé message_id        Γöé    R    Γöé    -   Γöé    R   Γöé    -   Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé message_qualifier    Γöé    O    Γöé    O   Γöé    O   Γöé    O   Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé luw_token        Γöé    R    Γöé    R   Γöé   R*   Γöé   R*   Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé version         Γöé    O    Γöé    O   Γöé    O   Γöé    O   Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé system_name       Γöé    O    Γöé    O   Γöé    O   Γöé    O   Γöé
  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 11. CICS OS/2 Version 1.20 ECI subset ΓòÉΓòÉΓòÉ

The CICS OS/2 Version 1.20 ECI call types can be used only in an application
running under OS/2, either in the same programmable workstation as the CICS for
OS/2 system or on a client in a CICS for OS/2 client/server configuration. The
use of these call types is not recommended for new applications.

The type of ECI call is controlled by the setting of the ECI-CALL-TYPE
parameter in the control block. For consistency with the documentation of the
ECI in CICS OS/2 Version 1.20, parameter names and call type values are given
here in COBOL format. This subset does not support the use of PL/I.

Calls can be either single or parallel, and either synchronous or asynchronous.
Several calls can be tied together in one logical unit of work by setting the
ECI-EXTEND-MODE parameter to ECI-EXTENDED.


ΓòÉΓòÉΓòÉ 11.1. Single calls ΓòÉΓòÉΓòÉ

Only one single call can be made at a time from an OS/2 process.

Single calls give no advantage over parallel calls; therefore, it is
recommended that parallel calls are used instead. Single calls are retained so
that programs written for earlier releases of CICS for OS/2 will continue to
run.

 Single synchronous call (ECI-SYNC-CALL)
           The calling program makes a single call and has to wait for the
           reply to come back. A parallel synchronous call can be used in
           exactly the same way.

 Single asynchronous call (ECI-ASYNC-CALL)
           Asynchronous processing is used for Presentation Manager programs
           only. The called program returns an initial response code to the
           calling program to indicate whether it accepts the request. If it
           accepts, the processing is carried out in a separate thread, and a
           message is posted to the PM window specified in ECI-WINDOW-HANDLE
           when it has finished. The format and contents of this message are
           described in Reply message formats.


ΓòÉΓòÉΓòÉ 11.2. Parallel calls ΓòÉΓòÉΓòÉ

Parallel processing of calls allows up to 16 logical units of work to be
handled simultaneously for each OS/2 process.

Before making the first call of a logical unit of work, ECI-LUW-TOKEN should be
set to zero. When the calling program makes the first call, ECI-LUW-TOKEN is
returned with a valid token. The program must use this token as input to later
calls in the logical unit of work to make the logical connection.

 Parallel synchronous call (ECI-SYNC-PARALLEL)
           Because this is a synchronous call, the calling thread is forced to
           wait for a reply before it can continue with another call. The
           returned token can then be used in extended calls.

 Parallel asynchronous call (ECI-ASYNC-PARALLEL)
           When the calling program makes the first call, ECI-LUW-TOKEN is
           returned with a valid token, which it uses as input to later calls
           in the logical unit of work to make the logical connection.

           Because this is an asynchronous call, the token is returned
           immediately and a Presentation Manager message indicating completion
           is posted later. A second call should not be made within this
           logical unit of work until the completion message is received.


ΓòÉΓòÉΓòÉ 11.3. Use of COMMAREA storage ΓòÉΓòÉΓòÉ

If you are making an asynchronous call (ECI-ASYNC-CALL or ECI-ASYNC-PARALLEL),
any COMMAREA storage passed on the call should not be reused until the
completion message has been posted, because CICS places the final contents of
the COMMAREA in this area.


ΓòÉΓòÉΓòÉ 11.4. Parameters for use with V1.20 ECI call types ΓòÉΓòÉΓòÉ

Input parameters for CICS OS/2 Version 1.20 call types shows the input
parameters for such an ECI call and, for each call type, whether the parameters
are required (R), optional (O), or not applicable. Where a parameter is shown
as optional, an initial field setting of nulls is expected if the caller does
not wish to use the parameter.

Parameter names and call type values are given in COBOL format; the
corresponding C parameters are in lowercase and include underscores instead of
hyphens as separators, and the corresponding C call types also have underscores
instead of hyphens.

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Table 5. Input parameters for CICS OS/2 Version 1.20 call types        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé Parameter, eci-     Γöé   ECI-   Γöé   ECI-   Γöé  ECI-SYNC- Γöé ECI-ASYNC- Γöé
Γöé             Γöé  SYNC-CALL  Γöé ASYNC-CALL Γöé  PARALLEL  Γöé  PARALLEL  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé call-type        Γöé    R    Γöé    R   Γöé    R   Γöé    R   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé program-name       Γöé  R, except  Γöé  R, except Γöé  R, except Γöé  R, except Γöé
Γöé             Γöé  when com-  Γöé  when com- Γöé  when com- Γöé  when com- Γöé
Γöé             Γöé  mitting or Γöé mitting or Γöé mitting or Γöé mitting or Γöé
Γöé             Γöé backing out Γöé  backing  Γöé  backing  Γöé  backing  Γöé
Γöé             Γöé       Γöé   out   Γöé   out   Γöé   out   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé userid          Γöé    R    Γöé    R   Γöé    R   Γöé    R   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé password         Γöé    R    Γöé    R   Γöé    R   Γöé    R   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé transid         Γöé    O    Γöé    O   Γöé    O   Γöé    O   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé commarea         Γöé    O    Γöé    O   Γöé    O   Γöé    O   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé commarea-length     Γöé    O    Γöé    O   Γöé    O   Γöé    O   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé timeout         Γöé    O    Γöé    O   Γöé    O   Γöé    O   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé extend-mode       Γöé    R    Γöé    R   Γöé    R   Γöé    R   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé window-handle      Γöé    -    Γöé    R   Γöé    -   Γöé    R   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé message-id        Γöé    -    Γöé    R   Γöé    -   Γöé    R   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé message-qualifier    Γöé    -    Γöé    O   Γöé    -   Γöé    O   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé luw-token        Γöé    -    Γöé    -   Γöé    R   Γöé    R   Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 12. ECI and EPI exits (CICS on Open Systems, Version 2) ΓòÉΓòÉΓòÉ

This chapter describes exits you can add to the EPI and ECI in the CICS on Open
Systems, Version 2 environment. The exits allow you to influence the processing
of ECI and EPI calls for certain application requests.

The chapter is organized as follows:

 Installing the exits

 Exit routine environment

 How the exit routines are described in the reference sections

 ECI exits reference

 EPI exits reference

 Diagnostic information


ΓòÉΓòÉΓòÉ 12.1. Installing the exits ΓòÉΓòÉΓòÉ

During ECI and EPI initialization, the client attempts to load the objects
described in ECI and EPI exits from the CICS binary directory, and to call the
corresponding entry points.

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé Table 6. ECI and EPI exits                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé      Γöé Object name           Γöé Entry point name         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ECI    Γöé cicseciexit           Γöé CICS_EciExitInit         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé EPI    Γöé cicsepiexit           Γöé CICS_EpiExitInit         Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Each entry point is passed a single parameter, a pointer to a structure that
contains a list of addresses. The initialization code of the program puts the
addresses of all the exits into the structure, and then the exits are called at
appropriate points in ECI and EPI processing. Since the exits are entered by
using the addresses supplied, you may give the exits any names you please, but
in this manual conventional names are used for the exits.

If the objects are not found, no exit processing occurs.

The following files are supplied with your CICS on Open Systems product to help
with programming the exits.

 cicseciexit.h
           A header files that defines:

    o inputs and outputs for each ECI exit

    o the format of the list of addresses for calling ECI exits

    o data structures used by ECI exits

    o return code values for ECI exits.

 cicseciexit.c
           Skeleton code for cicseciexit.

 cicseciexit.mk
           A makefile to reconstruct cicseciexit.

 cicsepiexit.h
           A header files that defines:

    o inputs and outputs for each EPI exit

    o the format of the list of addresses for calling EPI exits

    o data structures used by EPI exits

    o return code values for EPI exits.

 cicsepiexit.c
           Skeleton code for cicsepiexit.

 cicsepiexit.mk
           A makefile to reconstruct cicsepiexit.


ΓòÉΓòÉΓòÉ 12.2. Exit routine environment ΓòÉΓòÉΓòÉ

In your exits:

 o You must not make EPI or ECI calls.

 o You should avoid waits or long-running code. (It is quite possible that the
   exit is running on the applications user interface thread, and thus any
   delays in returning could have a bad effect on the system's responsiveness.)

 o You must not register as an RPC server.

 o You must follow the recommendations for multithreaded processes contained in
   Chapter 6 of Guide to Writing DCE Applications.


ΓòÉΓòÉΓòÉ 12.3. How the exit routines are described in the reference sections ΓòÉΓòÉΓòÉ

The exit routines are described under the following headings:

 o Purpose-describes the kind of processing that the exit is intended to
   perform.

 o When called-describes where in ECI or EPI processing the exit is called.

 o Parameters-describes the parameters supplied to the exit. Parameters are
   classified as follows:

    - Input-the exit may look at it, but must not change it.

    - Output-the exit must not look at it, but must store a value in it.

    - Input-output-the exit may look at it, and may store a value in it.

 o Return codes-describes the possible values the exit can return to the ECI or
   EPI. In each case the subsequent behavior of the ECI or EPI is described.

   Note:  The term FFST is used to denote first failure support technology.


ΓòÉΓòÉΓòÉ 12.4. ECI exits reference ΓòÉΓòÉΓòÉ

In this section the following exits are discussed:

 o CICS_EciInitializeExit
 o CICS_EciTerminateExit
 o CICS_EciExternalCallExit1
 o CICS_EciExternalCallExit2
 o CICS_EciSystemIdExit
 o CICS_EciDataSendExit
 o CICS_EciDataReturnExit

 Summary of ECI exits summarizes the exit names, the parameters passed to each
 exit, and the possible return codes.

  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  Γöé Table 7. Summary of ECI exits                         Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé Function name       Γöé Parameters   Γöé Return codes:           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EciInitializeExit   Γöé Version    Γöé CICS_EXIT_OK           Γöé
  Γöé              Γöé Anchor     Γöé CICS_EXIT_NO_EXIT         Γöé
  Γöé              Γöé        Γöé CICS_EXIT_CANT_INIT_EXITS     Γöé
  Γöé              Γöé        Γöé user-defined           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EciTerminateExit   Γöé Anchor     Γöé CICS_EXIT_OK           Γöé
  Γöé              Γöé        Γöé CICS_EXIT_BAD_ANCHOR       Γöé
  Γöé              Γöé        Γöé CICS_EXIT_BAD_STORAGE       Γöé
  Γöé              Γöé        Γöé user-defined           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EciExternalCallExit1 Γöé Anchor     Γöé CICS_EXIT_OK           Γöé
  Γöé              Γöé Token     Γöé CICS_EXIT_BAD_ANCHOR       Γöé
  Γöé              Γöé ParmPtr    Γöé CICS_EXIT_BAD_PARM        Γöé
  Γöé              Γöé        Γöé user-defined           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EciExternalCallExit2 Γöé Anchor     Γöé CICS_EXIT_OK           Γöé
  Γöé              Γöé Token     Γöé CICS_EXIT_BAD_ANCHOR       Γöé
  Γöé              Γöé ParmPtr    Γöé CICS_EXIT_BAD_PARM        Γöé
  Γöé              Γöé        Γöé user-defined           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EciSystemIdExit    Γöé Anchor     Γöé CICS_EXIT_OK           Γöé
  Γöé              Γöé Token     Γöé CICS_EXIT_BAD_ANCHOR       Γöé
  Γöé              Γöé ParmPtr    Γöé CICS_EXIT_BAD_PARM        Γöé
  Γöé              Γöé Reason     Γöé CICS_EXIT_GIVE_UP         Γöé
  Γöé              Γöé        Γöé user_defined           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EciDataSendExit    Γöé Anchor     Γöé CICS_EXIT_OK           Γöé
  Γöé              Γöé Token     Γöé CICS_EXIT_BAD_ANCHOR       Γöé
  Γöé              Γöé        Γöé CICS_EXIT_BAD_PARM        Γöé
  Γöé              Γöé        Γöé user_defined           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EciDataReturnExit   Γöé Anchor     Γöé CICS_EXIT_OK           Γöé
  Γöé              Γöé Token     Γöé CICS_EXIT_BAD_ANCHOR       Γöé
  Γöé              Γöé ParmPtr    Γöé CICS_EXIT_BAD_PARM        Γöé
  Γöé              Γöé        Γöé user_defined           Γöé
  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 12.4.1. Identification token ΓòÉΓòÉΓòÉ

In order for the exits to be able to relate calls for the same ECI request, an
identification token is passed in as a parameter to all exits except
CICS_EciInitializeExit and CICS_EciTerminateExit. The token is the same for
CICS_EciExternalCallExit1 and CICS_EciExternalCallExit2 that relate to the same
call, and on intervening CICS_EciDataSendExit, CICS_EciDataReturnExit, and
CICS_EciSystemIdExit exits. (Note that CICS_EciExternalCallExit1 and
CICS_EciExternalCallExit2 are not called for a reply solicitation request.)

The token is unique within the operating system that initiated the request, for
the duration of the request. It may be reused once the last exit for the
request has been called.

In the case of an extended logical unit of work, the token may be different on
different requests within the logical unit of work. (Since we allow reuse of
the token, and a new program link call may not be made until the ECI_GET_REPLY
request for the  previous asynchronous request has completed, it may also be
the same.)

The token is 8 bytes long. 8 null bytes is not a valid value for the token and
is not supplied to the exits.


ΓòÉΓòÉΓòÉ 12.4.2. Process model implementation ΓòÉΓòÉΓòÉ

All exits that relate to a particular request (i.e. have the same
identification token) are called in the context of the application process.


ΓòÉΓòÉΓòÉ 12.4.3. CICS_EciInitializeExit ΓòÉΓòÉΓòÉ

CICS_EciInitializeExit

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EciInitializeExit         Γöé Version                Γöé
Γöé                    Γöé Anchor                Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          To allow the user to set up an exit environment.

 When called

          On the first invocation of CICS_ExternalCall, for each process, after
          parameter validation has occurred.

 Parameters

          Version
                    Input parameter. The version of the ECI under which the
                    exit is running.

          Anchor
                    Output parameter. A pointer to a pointer that will be
                    passed to the ECI exits. The second pointer is not used by
                    the ECI; it is passed to the exits as supplied. You can
                    acquire storage in this exit and pass its address to the
                    other exits.

 Return codes

          CICS_EXIT_OK
                    The ECI continues processing this request, calling the
                    exits where appropriate.

          CICS_EXIT_NO_EXIT
                    The ECI continues processing this request, but does not
                    call any more exits.

          CICS_EXIT_CANT_INIT_EXITS
                    The ECI uses FFST, and then continues processing this
                    request, but does not call any more exits.

          user-defined
                    User-defined return codes must have a value not less than
                    CICS_EXIT_USER_BASE. The ECI uses FFST, and then continues
                    processing this request, but does not call any more exits.


ΓòÉΓòÉΓòÉ 12.4.4. CICS_EciTerminateExit ΓòÉΓòÉΓòÉ

CICS_EciTerminateExit

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EciTerminateExit         Γöé Anchor                Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          To allow the user to clean up the exit environment. Any storage
          acquired by CICS_EciInitializeExit must be released in this exit.

 When called

          On termination of the process that issued the CICS_EciInitializeExit.

 Parameters

          Anchor
                    Input parameter. The pointer set up by
                    CICS_EciInitializeExit.

 Return codes

          CICS_EXIT_OK
                    Termination continues.

          CICS_EXIT_BAD_ANCHOR
                    The ECI uses FFST, and then continues with termination.

          CICS_EXIT_BAD_STORAGE
                    The ECI uses FFST, and then continues with termination.

          user-defined
                    User-defined return codes must have a value not less than
                    CICS_EXIT_USER_BASE. The ECI uses FFST, and then continues
                    with termination.


ΓòÉΓòÉΓòÉ 12.4.5. CICS_EciExternalCallExit1 ΓòÉΓòÉΓòÉ

CICS_EciExternalCallExit1

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EciExternalCallExit1       Γöé Anchor                Γöé
Γöé                    Γöé Token                 Γöé
Γöé                    Γöé ParmPtr                Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          To allow the user to pick the best system to run the program. This
          exit is called exactly once on each program link and each status
          information call. It is not called on a reply solicitation call.

 When called

          On invocation of CICS_ExternalCall, for each program link call and
          each status information call, after the ECI has validated the
          parameters.

 Parameters

          Anchor
                    Input parameter. The pointer set up by
                    CICS_EciInitializeExit.

          Token
                    Input parameter. The identification token established by
                    the ECI for this request.

          ParmPtr
                    Input parameter. A pointer to the ECI parameter block. The
                    exit must treat all fields in the ECI parameter block as
                    inputs, except the eci_system_name field, which it may
                    change.

 Return codes

          CICS_EXIT_OK
                    The ECI continues to process the request with the
                    eci_system_name now specified in the ECI parameter block.

          CICS_EXIT_BAD_ANCHOR
                    The ECI uses FFST, and then continues to process the
                    request with the eci_system_name now specified in the ECI
                    parameter block.

          CICS_EXIT_BAD_PARM
                    The ECI uses FFST, and then continues to process the
                    request with the eci_system_name now specified in the ECI
                    parameter block.

          user-defined
                    User-defined return codes must have a value not less than
                    CICS_EXIT_USER_BASE. The ECI uses FFST, and then continues
                    to process the request with the eci_system_name now
                    specified in the ECI parameter block.


ΓòÉΓòÉΓòÉ 12.4.5.1. Note on selection of systems ΓòÉΓòÉΓòÉ

There is a limited set of conditions under which the exit may select a new
system. The exit may select a system if the call is a program link or status
information call, and if a new logical unit of work is being started. In other
cases, the exit should return CICS_EXIT_OK.

If the calling application has put binary zeros as the system name in the
parameter block, then the application is expecting that the system will be
dynamically selected, and the exit may safely select the system.

If however the calling application has placed a system name in the parameter
block, or if the application is a version 0 application, then it may not be
expecting the target system to change, and application errors could result. In
this case the exit would generally return without specifying a replacement
system, with the result that the specified or default system name is to be
used. If the exit chooses to change the selected system in this situation, then
it may do so, but the following should be borne in mind.

          o The exit routine must be sensitive to whether or not the
            modification of the target system will cause errors in the ECI
            application running on the client.

          o The exit routine must maintain a knowledge base, keyed on
            appropriate data available to it, to enable it to determine whether
            this modification is acceptable to the client application.


ΓòÉΓòÉΓòÉ 12.4.6. CICS_EciExternalCallExit2 ΓòÉΓòÉΓòÉ

CICS_EciExternalCallExit2

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EciExternalCallExit2       Γöé Anchor                Γöé
Γöé                    Γöé Token                 Γöé
Γöé                    Γöé ParmPtr                Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          To allow the user to see the results of synchronous ECI calls for
          information gathering purposes only. This exit is called exactly once
          on every application program link or status information call. It is
          not called on reply solicitation calls.

 When called

          Before the ECI call returns to the application, and after the return
          data is filled into the ECI parameter block.

 Parameters

          Anchor
                    Input parameter. The pointer set up by
                    CICS_EciInitializeExit.

          Token
                    Input parameter. The identification token established by
                    the ECI for this request.

          ParmPtr
                    Input parameter. A pointer to the ECI parameter block. The
                    exit must treat all fields in the ECI parameter block as
                    inputs.

 Return codes

          CICS_EXIT_OK
                    The ECI returns control to the application that issued the
                    CICS_ExternalCall request.

          CICS_EXIT_BAD_ANCHOR
                    The ECI uses FFST, and then returns control to the
                    application that issued the CICS_ExternalCall request.

          CICS_EXIT_BAD_PARM
                    The ECI uses FFST, and then returns control to the
                    application that issued the CICS_ExternalCall request.

          user-defined
                    User-defined return codes must have a value not less than
                    CICS_EXIT_USER_BASE. The ECI uses FFST, and then returns
                    control to the application that issued the
                    CICS_ExternalCall request.


ΓòÉΓòÉΓòÉ 12.4.7. CICS_EciSystemIdExit ΓòÉΓòÉΓòÉ

CICS_EciSystemIdExit

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EciSystemIdExit          Γöé Anchor                Γöé
Γöé                    Γöé Token                 Γöé
Γöé                    Γöé ParmPtr                Γöé
Γöé                    Γöé Reason                Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          To allow the user to supply a new system name when the name supplied
          in the ECI parameter block is not valid.

 When called

          This exit is called when an error occurs that may be corrected by
          selection of a new system, userid, or password. This is when the ECI
          would return a code of ECI_ERR_NO_CICS or ECI_ERR_UNKNOWN_SERVER or
          ECI_ERR_SECURITY_ERROR. It may be called when either when the client
          detects an error before data is sent to the server, or after data
          returns from the server.

 Parameters

          Anchor
                    Input parameter. The pointer set up by
                    CICS_EciInitializeExit.

          Token
                    Input parameter. The identification token established by
                    the ECI for this request.

          ParmPtr
                    Input parameter. A pointer to the ECI parameter block. The
                    exit must treat all fields in the ECI parameter block as
                    inputs, except the following, which it may set:

             o eci_system_name
             o eci_userid
             o eci_password.

          Reason
                    Input parameter. The reason code that explains why the
                    application request has not so far succeeded.

 Return codes

          CICS_EXIT_OK
                    The ECI retries the application call using the new
                    parameters in the ECI parameter block. (The CICS program
                    communication area supplied by the application to the
                    CICS_ExternalCall is preserved.) The application callback
                    routine will not be called, nor will
                    CICS_EciExternalCallExit2.

          CICS_EXIT_BAD_ANCHOR
                    The ECI uses FFST, and then returns to the application that
                    issued the CICS_ExternalCall request.

          CICS_EXIT_BAD_PARM
                    The ECI uses FFST, and then returns to the application that
                    issued the CICS_ExternalCall request.

          CICS_EXIT_GIVE_UP
                    The ECI returns to the application that issued the
                    CICS_ExternalCall request.

          user-defined
                    User-defined return codes must have a value not less than
                    CICS_EXIT_USER_BASE. The ECI uses FFST, and then retries
                    the application call as described for CICS_EXIT_OK.


ΓòÉΓòÉΓòÉ 12.4.8. CICS_EciDataSendExit ΓòÉΓòÉΓòÉ

CICS_EciDataSendExit

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EciDataSendExit          Γöé Anchor                Γöé
Γöé                    Γöé Token                 Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          To allow the user to time calls for performance analysis.

 When called

          As close as possible to the time that the request  will be sent to
          the server.

 Parameters

          Anchor
                    Input parameter. The pointer set up by
                    CICS_EciInitializeExit.

          Token
                    Input parameter. The identification token established by
                    the ECI for this request.

 Return codes

          CICS_EXIT_OK
                    The ECI continues processing the request.

          CICS_EXIT_BAD_ANCHOR
                    The ECI uses FFST, and then continues processing the
                    request.

          CICS_EXIT_BAD_PARM
                    The ECI uses FFST, and then continues processing the
                    request.

          user-defined
                    User-defined return codes must have a value not less than
                    CICS_EXIT_USER_BASE. The ECI uses FFST, and then continues
                    processing the request.


ΓòÉΓòÉΓòÉ 12.4.9. CICS_EciDataReturnExit ΓòÉΓòÉΓòÉ

CICS_EciDataReturnExit

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EciDataReturnExit         Γöé Anchor                Γöé
Γöé                    Γöé Token                 Γöé
Γöé                    Γöé ParmPtr                Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          To allow the user to time calls for performance analysis.

 When called

          As close as possible to the time that the response from the server
          has been received, and the ECI block and commarea data for eventual
          return to the application has been built. It is also called if there
          is a timeout because of a lack of response from the server.

 Parameters

          Anchor
                    Input parameter. The pointer set up by
                    CICS_EciInitializeExit.

          Token
                    Input parameter. The identification token established by
                    the ECI for this request.

          ParmPtr
                    Input parameter. A pointer to the ECI parameter block. The
                    exit must treat all fields in the ECI parameter block as
                    inputs.

 Return codes

          CICS_EXIT_OK
                    The ECI continues processing the request.

          CICS_EXIT_BAD_ANCHOR
                    The ECI uses FFST, and then continues processing the
                    request.

          CICS_EXIT_BAD_PARM
                    The ECI uses FFST, and then continues processing the
                    request.

          user-defined
                    User-defined return codes must have a value not less than
                    CICS_EXIT_USER_BASE. The ECI uses FFST, and then continues
                    processing the request.


ΓòÉΓòÉΓòÉ 12.5. EPI exits reference ΓòÉΓòÉΓòÉ

In this section the following exits are discussed:

 o CICS_EpiInitializeExit
 o CICS_EpiTerminateExit
 o CICS_EpiAddTerminalExit
 o CICS_EpiTermIdExit
 o CICS_EpiStartTranExit
 o CICS_EpiReplyExit
 o CICS_EpiDelTerminalExit
 o CICS_EpiGetEventExit
 o CICS_EpiSystemIdExit
 o CICS_EpiTranFailedExit

 Summary of EPI exits summarizes the exit names, the parameters passed to each
 exit, and the possible return codes.

  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  Γöé Table 8. Summary of EPI exits                         Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé Function name       Γöé Parameters   Γöé Return codes:           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EpiInitializeExit   Γöé Version    Γöé CICS_EXIT_OK           Γöé
  Γöé              Γöé Anchor     Γöé CICS_EXIT_NO_EXIT         Γöé
  Γöé              Γöé        Γöé CICS_EXIT_CANT_INIT_EXITS     Γöé
  Γöé              Γöé        Γöé user-defined           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EpiTerminateExit   Γöé Anchor     Γöé CICS_EXIT_OK           Γöé
  Γöé              Γöé        Γöé CICS_EXIT_BAD_ANCHOR       Γöé
  Γöé              Γöé        Γöé CICS_EXIT_BAD_STORAGE       Γöé
  Γöé              Γöé        Γöé user-defined           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EpiAddTerminalExit  Γöé Anchor     Γöé CICS_EXIT_OK           Γöé
  Γöé              Γöé NameSpace   Γöé CICS_EXIT_DONT_ADD_TERMINAL    Γöé
  Γöé              Γöé System     Γöé CICS_EXIT_BAD_ANCHOR       Γöé
  Γöé              Γöé NetName    Γöé CICS_EXIT_BAD_PARM        Γöé
  Γöé              Γöé DevType    Γöé user-defined           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EpiTermIdExit     Γöé Anchor     Γöé CICS_EXIT_OK           Γöé
  Γöé              Γöé TermIndex   Γöé CICS_EXIT_BAD_ANCHOR       Γöé
  Γöé              Γöé System     Γöé CICS_EXIT_BAD_PARM        Γöé
  Γöé              Γöé        Γöé user-defined           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EpiStartTranExit   Γöé Anchor     Γöé CICS_EXIT_OK           Γöé
  Γöé              Γöé TransId    Γöé CICS_EXIT_BAD_ANCHOR       Γöé
  Γöé              Γöé Data      Γöé CICS_EXIT_BAD_PARM        Γöé
  Γöé              Γöé Size      Γöé user-defined           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EpiReplyExit     Γöé Anchor     Γöé CICS_EXIT_OK           Γöé
  Γöé              Γöé TermIndex   Γöé CICS_EXIT_BAD_ANCHOR       Γöé
  Γöé              Γöé Data      Γöé CICS_EXIT_BAD_PARM        Γöé
  Γöé              Γöé Size      Γöé user_defined           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EpiDelTerminalExit  Γöé Anchor     Γöé CICS_EXIT_OK           Γöé
  Γöé              Γöé TermIndex   Γöé CICS_EXIT_BAD_ANCHOR       Γöé
  Γöé              Γöé        Γöé CICS_EXIT_BAD_PARM        Γöé
  Γöé              Γöé        Γöé user_defined           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EpiGetEventExit    Γöé Anchor     Γöé CICS_EXIT_OK           Γöé
  Γöé              Γöé TermIndex   Γöé CICS_EXIT_BAD_ANCHOR       Γöé
  Γöé              Γöé Wait      Γöé CICS_EXIT_BAD_PARM        Γöé
  Γöé              Γöé Event     Γöé user_defined           Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EpiSystemIdExit    Γöé Anchor     Γöé CICS_EXIT_OK           Γöé
  Γöé              Γöé NameSpace   Γöé CICS_EXIT_DONT_ADD_TERMINAL    Γöé
  Γöé              Γöé System     Γöé CICS_EXIT_BAD_ANCHOR       Γöé
  Γöé              Γöé NetName    Γöé CICS_EXIT_BAD_PARM        Γöé
  Γöé              Γöé DevType    Γöé user_defined           Γöé
  Γöé              Γöé FailedSystem  Γöé                  Γöé
  Γöé              Γöé Reason     Γöé                  Γöé
  Γöé              Γöé SubReason   Γöé                  Γöé
  Γöé              Γöé UserId     Γöé                  Γöé
  Γöé              Γöé PassWord    Γöé                  Γöé
  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  Γöé CICS_EpiTranFailedExit   Γöé Anchor     Γöé CICS_EXIT_OK           Γöé
  Γöé              Γöé TermIndex   Γöé CICS_EXIT_BAD_ANCHOR       Γöé
  Γöé              Γöé Wait      Γöé CICS_EXIT_BAD_PARM        Γöé
  Γöé              Γöé Event     Γöé user_defined           Γöé
  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 12.5.1. CICS_EpiInitializeExit ΓòÉΓòÉΓòÉ

CICS_EpiInitializeExit

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EpiInitializeExit         Γöé Version                Γöé
Γöé                    Γöé Anchor                Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          To allow the user to set up an exit environment.

 When called

          On each invocation of CICS_EpiInitialize, after the EPI has validated
          the parameters.

 Parameters

          Version
                    Input parameter. The version of the EPI under which the
                    exit is running.

          Anchor
                    Output parameter. A pointer to a pointer that will be
                    passed to the EPI exits. The second pointer is not used by
                    the EPI; it is passed to the exits as supplied. You can
                    acquire storage in this exit and pass its address to the
                    other exits.

 Return codes

          CICS_EXIT_OK
                    The EPI continues processing this request, calling the
                    exits where appropriate.

          CICS_EXIT_NO_EXIT
                    The EPI continues processing this request, but does not
                    call any more exits.

          CICS_EXIT_CANT_INIT_EXITS
                    The EPI uses FFST, and then continues processing this
                    request, but does not call any more exits.

          user-defined
                    User-defined return codes must have a value not less than
                    CICS_EXIT_USER_BASE. The EPI uses FFST, and then continues
                    processing this request, but does not call any more exits.


ΓòÉΓòÉΓòÉ 12.5.2. CICS_EpiTerminateExit ΓòÉΓòÉΓòÉ

CICS_EpiTerminateExit

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EpiTerminateExit         Γöé Anchor                Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          To allow the user to clean up the exit environment. Any storage
          acquired by CICS_EpiInitializeExit must be released in this exit.

 When called

          On each invocation of CICS_EpiTerminate, after the EPI has validated
          the parameters.

 Parameters

          Anchor
                    Input parameter. The pointer set up by
                    CICS_EpiInitializeExit.

 Return codes

          CICS_EXIT_OK
                    Termination continues.

          CICS_EXIT_BAD_ANCHOR
                    The EPI uses FFST, and then continues with termination.

          CICS_EXIT_BAD_STORAGE
                    The EPI uses FFST, and then continues with termination.

          user-defined
                    User-defined return codes must have a value not less than
                    CICS_EXIT_USER_BASE. The EPI uses FFST, and then continues
                    with termination.


ΓòÉΓòÉΓòÉ 12.5.3. CICS_EpiAddTerminalExit ΓòÉΓòÉΓòÉ

CICS_EpiAddTerminalExit

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EpiAddTerminalExit        Γöé Anchor                Γöé
Γöé                    Γöé NameSpace               Γöé
Γöé                    Γöé System                Γöé
Γöé                    Γöé NetName                Γöé
Γöé                    Γöé DevType                Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          To allow the user to select a server, or override the one passed to
          CICS_EpiAddTerminal in the System parameter.

 When called

          On each invocation of CICS_EpiAddTerminal, after the EPI has
          validated the parameters.

 Parameters

          Anchor
                    Input parameter. The pointer storage set up by
                    CICS_EpiInitializeExit.

          NameSpace
                    Input-output parameter. On input, its value depends on the
                    value supplied for the NameSpace parameter of the
                    CICS_EpiAddTerminal call to which this exit relates:

             o If a null pointer was supplied, this input is a pointer to a
               null string.

             o If a non-null pointer was supplied, this input is that pointer.
                    On output, it will be used by the EPI in the same way as
                    the value specified on the call would have been used.

          System
                    Input-output parameter. On input, it is the value supplied
                    for the System parameter of the CICS_EpiAddTerminal call to
                    which this exit relates. On output, it will be used by the
                    EPI in the same way as the value specified on the call
                    would have been used.

          NetName
                    Input-output parameter. On input, it is the value supplied
                    for the NetName parameter of the CICS_EpiAddTerminal call
                    to which this exit relates. On output, it will be used by
                    the EPI in the same way as the value specified on the call
                    would have been used.

          DevType
                    Input-output parameter. On input, it is the value supplied
                    for the DevType parameter of the CICS_EpiAddTerminal call
                    to which this exit relates. On output, it will be used by
                    the EPI in the same way as the value specified on the call
                    would have been used.

 Return codes

          CICS_EXIT_OK
                    Processing continues with the output values of NameSpace,
                    System, NetName, and DevType.

          CICS_EXIT_DONT_ADD_TERMINAL
                    The CICS_EpiAddTerminal is ended with a return code of
                    CICS_EPI_ERR_FAILED. If the application uses
                    CICS_EpiGetSysError, the value 5 is returned in the Value
                    field of the CICS_EpiSysError_t structure.

          CICS_EXIT_BAD_ANCHOR
                    The EPI uses FFST, and then continues as for CICS_EXIT_OK.

          CICS_EXIT_BAD_PARM
                    The EPI uses FFST, and then continues as for CICS_EXIT_OK.

          user-defined
                    User-defined return codes must have a value not less than
                    CICS_EXIT_USER_BASE. The EPI uses FFST, and then continues
                    as for CICS_EXIT_OK.


ΓòÉΓòÉΓòÉ 12.5.3.1. Note on selection of systems ΓòÉΓòÉΓòÉ

If the calling application does not specify system name in its parameter list,
then it is expecting that the system will be dynamically selected, and the exit
may safely select the system.

If however the calling application specifies a system name, then it may not be
expecting the target system to change and application errors could result. In
this case the exit would generally not specify a replacement system, with the
result that the specified or default system name, device type, etc. is to be
used. If the exit chooses to change the selected system in this situation, then
it may do so, but the following should be borne in mind.

          o The exit routine must be sensitive to whether or not the
            modification of the target system will cause errors in the EPI
            application running on the client.

          o The exit routine must maintain a knowledge base, keyed on
            appropriate data available to it, to enable it to determine whether
            this modification is acceptable to the client application.


ΓòÉΓòÉΓòÉ 12.5.3.2. CICS_EpiAddTerminalExit and CICS_EpiSystemIdExit ΓòÉΓòÉΓòÉ

The relationship between these exits is as follows. The exits will get multiple
chances to make a selection of the system. The first chance will always occur
on the CICS_EpiAddTerminalExit. This exit will only receive the parameters
passed by the application to CICS_EpiAddTerminal. If an error occurs when CICS
tries to add the terminal (whether or not the exit has made a selection) then
CICS_EpiSystemIdExit will be called. CICS_EpiSystemIdExit will additionally be
passed the error that occurred on the attempt to add the terminal, and will get
a chance to correct the error. This continues to occur until either a terminal
is successfully added, or until CICS_EpiSystemIdExit signals to give up.

If no error occurs on the attempt to add the terminal, then
CICS_EpiSystemIdExit will not be called.


ΓòÉΓòÉΓòÉ 12.5.4. CICS_EpiTermIdExit ΓòÉΓòÉΓòÉ

CICS_EpiTermIdExit

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EpiTermIdExit           Γöé Anchor                Γöé
Γöé                    Γöé TermIndex               Γöé
Γöé                    Γöé System                Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          To allow the user to know the terminal index allocated after a
          successfull call to CICS_EpiAddTerminal.

 When called

          On each invocation of CICS_EpiAddTerminal, after the server has
          allocated the terminal.

 Parameters

          Anchor
                    Input parameter. The pointer storage set up by
                    CICS_EpiInitializeExit.

          TermIndex
                    Input parameter. A pointer to the terminal index for the
                    terminal resource just reserved or installed.

          System
                    Input parameter. A pointer to a null-terminated string that
                    specifies the name of the server in which the terminal
                    resource has been reserved or installed.

 Return codes

          CICS_EXIT_OK
                    Processing continues.

          CICS_EXIT_BAD_ANCHOR
                    The EPI uses FFST, and then continues as for CICS_EXIT_OK.

          CICS_EXIT_BAD_PARM
                    The EPI uses FFST, and then continues as for CICS_EXIT_OK.

          user-defined
                    User-defined return codes must have a value not less than
                    CICS_EXIT_USER_BASE. The EPI uses FFST, and then continues
                    as for CICS_EXIT_OK.


ΓòÉΓòÉΓòÉ 12.5.5. CICS_EpiStartTranExit ΓòÉΓòÉΓòÉ

CICS_EpiStartTranExit

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EpiStartTranExit         Γöé Anchor                Γöé
Γöé                    Γöé TransId                Γöé
Γöé                    Γöé Data                 Γöé
Γöé                    Γöé Size                 Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          To allow the user to see when a transaction is started, for
          information gathering purposes. This exit will not select a system,
          and has no return data.

 When called

          On invocation of CICS_EpiStartTran, after the EPI has validated the
          parameters.

 Parameters

          Anchor
                    Input parameter. The pointer set up by
                    CICS_EpiInitializeExit.

          TransId
                    Input parameter. The value supplied for the TransId
                    parameter of the CICS_EpiStartTran call to which this exit
                    relates.

          Data
                    Input parameter. The value supplied for the Data parameter
                    of the CICS_EpiStartTran call to which this exit relates.

          Size
                    Input parameter. The value supplied for the Size parameter
                    of the CICS_EpiStartTran call to which this exit relates.

 Return codes

          CICS_EXIT_OK
                    Processing of the CICS_EpiStartTran call continues.

          CICS_EXIT_BAD_ANCHOR
                    The EPI uses FFST, and then processing of the
                    CICS_EpiStartTran call continues.

          CICS_EXIT_BAD_PARM
                    The EPI uses FFST, and then processing of the
                    CICS_EpiStartTran call continues.

          user-defined
                    User-defined return codes must have a value not less than
                    CICS_EXIT_USER_BASE. The EPI uses FFST, and then processing
                    of the CICS_EpiStartTran call continues.


ΓòÉΓòÉΓòÉ 12.5.6. CICS_EpiReplyExit ΓòÉΓòÉΓòÉ

CICS_EpiReplyExit

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EpiReplyExit           Γöé Anchor                Γöé
Γöé                    Γöé TermIndex               Γöé
Γöé                    Γöé Data                 Γöé
Γöé                    Γöé Size                 Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          To allow the user to see when a transaction is replied to, for
          information gathering purposes.

 When called

          On invocation of CICS_EpiReply, after the EPI has validated the
          parameters.

 Parameters

          Anchor
                    Input parameter. The pointer set up by
                    CICS_EpiInitializeExit.

          TermIndex
                    Input parameter. The value supplied for the TermIndex
                    parameter of the CICS_EpiReply call to which this exit
                    relates.

          Data
                    Input parameter. The value supplied for the Data parameter
                    of the CICS_EpiReply call to which this exit relates.

          Size
                    Input parameter. The value supplied for the Size parameter
                    of the CICS_EpiReply call to which this exit relates.

 Return codes

          CICS_EXIT_OK
                    Processing of the CICS_EpiReply call continues.

          CICS_EXIT_BAD_ANCHOR
                    The EPI uses FFST, and then processing of the CICS_EpiReply
                    call continues.

          CICS_EXIT_BAD_PARM
                    The EPI uses FFST, and then processing of the CICS_EpiReply
                    call continues.

          user-defined
                    User-defined return codes must have a value not less than
                    CICS_EXIT_USER_BASE. The EPI uses FFST, and then processing
                    of the CICS_EpiReply call continues.


ΓòÉΓòÉΓòÉ 12.5.7. CICS_EpiDelTerminalExit ΓòÉΓòÉΓòÉ

CICS_EpiDelTerminalExit

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EpiDelTerminalExit        Γöé Anchor                Γöé
Γöé                    Γöé TermIndex               Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          To allow the user to clean up any terminal-related data structures.

 When called

          On invocation of CICS_EpiDelTerminal, after the EPI has validated the
          parameters.

 Parameters

          Anchor
                    Input parameter. The pointer set up by
                    CICS_EpiInitializeExit.

          TermIndex
                    Input parameter. The value supplied for the TermIndex
                    parameter of the CICS_EpiDelTerminal call to which this
                    exit relates.

 Return codes

          CICS_EXIT_OK
                    Processing of the CICS_EpiDelTerminal call continues.

          CICS_EXIT_BAD_ANCHOR
                    The EPI uses FFST, and then processing of the
                    CICS_EpiDelTerminal call continues.

          CICS_EXIT_BAD_PARM
                    The EPI uses FFST, and then processing of the
                    CICS_EpiDelTerminal call continues.

          user-defined
                    User-defined return codes must have a value not less than
                    CICS_EXIT_USER_BASE. The EPI uses FFST, and then processing
                    of the CICS_EpiDelTerminal call continues.


ΓòÉΓòÉΓòÉ 12.5.8. CICS_EpiGetEventExit ΓòÉΓòÉΓòÉ

CICS_EpiGetEventExit

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EpiGetEventExit          Γöé Anchor                Γöé
Γöé                    Γöé TermIndex               Γöé
Γöé                    Γöé Wait                 Γöé
Γöé                    Γöé Event                 Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          To allow the user to collect data relating to the event that has
          arrived.

 When called

          Immediately before CICS_EpiGetEvent returns to the caller. The exit
          can then examine the data returned, time the response from the
          system, etc.

 Parameters

          Anchor
                    Input parameter. The pointer set up by
                    CICS_EpiInitializeExit.

          TermIndex
                    Input parameter. The value to be returned to the
                    application in the TermIndex parameter of the
                    CICS_EpiGetEvent call to which this exit relates.

          Wait
                    Input parameter. The value supplied for the Wait parameter
                    of the CICS_EpiGetEvent call to which this exit relates.

          Event
                    Input parameter. The value to be returned to the
                    application in the Event parameter of the CICS_EpiGetEvent
                    call to which this exit relates.

 Return codes

          CICS_EXIT_OK
                    Processing of the CICS_EpiGetEvent call continues.

          CICS_EXIT_BAD_ANCHOR
                    The EPI uses FFST, and then processing of the
                    CICS_EpiGetEvent call continues.

          CICS_EXIT_BAD_PARM
                    The EPI uses FFST, and then processing of the
                    CICS_EpiGetEvent call continues.

          user-defined
                    User-defined return codes must have a value not less than
                    CICS_EXIT_USER_BASE. The EPI uses FFST, and then processing
                    of the CICS_EpiGetEvent call continues.


ΓòÉΓòÉΓòÉ 12.5.9. CICS_EpiSystemIdExit ΓòÉΓòÉΓòÉ

CICS_EpiSystemIdExit

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EpiSystemIdExit          Γöé Anchor                Γöé
Γöé                    Γöé NameSpace               Γöé
Γöé                    Γöé System                Γöé
Γöé                    Γöé NetName                Γöé
Γöé                    Γöé DevType                Γöé
Γöé                    Γöé FailedSystem             Γöé
Γöé                    Γöé Reason                Γöé
Γöé                    Γöé SubReason               Γöé
Γöé                    Γöé UserId                Γöé
Γöé                    Γöé PassWord               Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          To allow the user to supply a new system name when the value supplied
          for CICS_Epi_AddTerminal was invalid.

 When called

          Immediately before CICS_EpiAddTerminal returns to the application
          when an error occurred while trying to add the terminal. The error
          can be CICS_EPI_ERR_SYSTEM or CICS_EPI_ERR_FAILED. It occurs whether
          or not CICS_EpiAddTerminalExit has been called previously.

          Note:  On some systems the completion of CICS_EpiAddTerminal is
                 returned to the application asynchronously, and in this case
                 this exit will be called asynchronously.

 Parameters

          Anchor
                    Input parameter. The pointer set up by
                    CICS_EpiInitializeExit.

          NameSpace
                    Input-output parameter. The NameSpace parameter used in the
                    failed CICS_EpiAddTerminal.

          System
                    Input-output parameter. The System parameter used in the
                    failed CICS_EpiAddTerminal.

          NetName
                    Input-output parameter. The NetName parameter used in the
                    failed CICS_EpiAddTerminal.

          DevType
                    Input-output parameter. The DevType parameter used in the
                    failed CICS_EpiAddTerminal.

          FailedSystem
                    Input parameter. The identifier of the system on which the
                    failure occurred.

          Reason
                    Input parameter. The reason for the failure:.
                    CICS_EPI_ERR_SYSTEM  or CICS_EPI_ERR_FAILED.

          SubReason
                    Input parameter. More about the failure. If the reason is
                    CICS_EPI_ERR_FAILED, this is the value that appears in the
                    Cause field of the CICS_EpiSysError_t structure.

          UserId
                    Output parameter. Not used.

          PassWord
                    Output parameter. Not used.

 Return codes

          CICS_EXIT_OK
                    The EPI will retry the CICS_EpiAddTerminal call using the
                    values specified as output of this exit. Note that in this
                    case the considerations described in
                    CICS_EpiAddTerminalExit apply.

          CICS_EXIT_DONT_ADD_TERMINAL
                    The CICS_EpiAddTerminal is ended with a return code of
                    CICS_EPI_ERR_FAILED. If the application uses
                    CICS_EpiGetSysError, the value 5 is returned in the Value
                    field of the CICS_EpiSysError_t structure.

          CICS_EXIT_BAD_ANCHOR
                    The EPI uses FFST, and then the error that caused the exit
                    to be called is returned to the application.

          CICS_EXIT_BAD_PARM
                    The EPI uses FFST, and then the error that caused the exit
                    to be called is returned to the application.

          user-defined
                    User-defined return codes must have a value not less than
                    CICS_EXIT_USER_BASE. The EPI uses FFST, and then the error
                    that caused the exit to be called is returned to the
                    application.
          Retry the CICS_EpiAddTerminal call using the system specified as
          output of this exit. Note that in this case the considerations
          described in CICS_EpiAddTerminalExit apply.


ΓòÉΓòÉΓòÉ 12.5.10. CICS_EpiTranFailedExit ΓòÉΓòÉΓòÉ

CICS_EpiTranFailedExit

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CICS_EpiTranFailedExit         Γöé Anchor                Γöé
Γöé                    Γöé TermIndex               Γöé
Γöé                    Γöé Wait                 Γöé
Γöé                    Γöé Event                 Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 Purpose

          To allow the user to collect data when a transaction abends or a
          terminal fails.

 When called

          Immediately before CICS_EpiGetEvent returns to the caller, with or
          without GetEventExit, when the event is CICS_EPI_EVENT_END_TRAN, and
          the AbendCode field is not blank.

          Note that there are some failures on remote systems that can occur
          and will simply cause the presentation of a 3270 data stream with an
          error message and no abend code in the CICS_EPI_EVENT_END_TRAN. This
          error message may not even occur on the same event as the
          CICS_EPI_EVENT_END_TRAN. If the exit requires to handle this
          situation, it may monitor it through CICS_EpiGetEventExit and scan
          the appropriate 3270 data streams.

 Parameters

          Anchor
                    Input parameter. The pointer set up by
                    CICS_EpiInitializeExit.

          TermIndex
                    Input parameter. The value to be returned to the
                    application in the TermIndex parameter of the
                    CICS_EpiGetEvent call to which this exit relates.

          Wait
                    Input parameter. The value supplied for the Wait parameter
                    of the CICS_EpiGetEvent call to which this exit relates.

          Event
                    Input parameter. The value to be returned to the
                    application in the Event parameter of the CICS_EpiGetEvent
                    call to which this exit relates.

 Return codes

          CICS_EXIT_OK
                    Processing of the CICS_EpiGetEvent call continues.

          CICS_EXIT_BAD_ANCHOR
                    The EPI uses FFST, and then processing of the
                    CICS_EpiGetEvent call continues.

          CICS_EXIT_BAD_PARM
                    The EPI uses FFST, and then processing of the
                    CICS_EpiGetEvent call continues.

          user-defined
                    User-defined return codes must have a value not less than
                    CICS_EXIT_USER_BASE. The EPI uses FFST, and then processing
                    of the CICS_EpiGetEvent call continues.


ΓòÉΓòÉΓòÉ 12.6. Diagnostic information ΓòÉΓòÉΓòÉ

CICS will trace the input parameters to the exits immediately before they are
called, and the output of the exit when the exit returns. CICS tracing will not
be available for use within the exit.


ΓòÉΓòÉΓòÉ 13. Sending your comments to IBM ΓòÉΓòÉΓòÉ

If you especially like or dislike anything about this book, please use one of
the methods listed below to send your comments to IBM.

Feel free to comment on what you regard as specific errors or omissions, and on
the accuracy, organization, subject matter, or completeness of this book.

Please limit your comments to the information in this book and the way in which
the information is presented.

To request additional publications, or to ask questions or make comments about
the functions of IBM products or systems, you should talk to your IBM
representative or to your IBM authorized remarketer.

When you send comments to IBM, you grant IBM a nonexclusive right to use or
distribute your comments in any way it believes appropriate, without incurring
any obligation to you.

You can send your comments to IBM in any of the following ways:

 o By fax:

    - From outside the U.K., after your international access code use 44 1962
      870229
    - From within the U.K., use 01962 870229

 o Electronically, use the appropriate network ID:

    - IBM Mail Exchange:  GBIBM2Q9 at IBMMAIL
    - IBMLink:  WINVMD(IDRCF)
    - Internet:  [e-mail]

 Whichever you use, ensure that you include:

 o The publication number and title
 o The page number or topic to which your comment applies
 o Your name and address/telephone number/fax number/network ID.