TXSeries for Multiplatforms Front-End Programming Interface for Windows Version 6.2

TXSeries for Multiplatforms

Front-End Programming Interface for Windows Version 6.2

SC34-6747-01

Note Before using this information and the product it supports, be sure to read the general information under Notices on page 91.

Second Edition (January 2008) This edition replaces SC34-6747-00. Order publications through your IBM representative or through the IBM branch office serving your locality. Copyright International Business Machines Corporation 1999, 2008. All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

About this book . . . . . . . . . . . . . . . . . . . . . . . . xi Who should read this book . . . . . . . . . . . . . . . . . . . . . xi Document organization . . . . . . . . . . . . . . . . . . . . . . xi Related Information . . . . . . . . . . . . . . . . . . . . . . . xii Conventions used in this book . . . . . . . . . . . . . . . . . . . xii How to send your comments . . . . . . . . . . . . . . . . . . . . xiii

Chapter 1. Introducing FEPI . . . . . . . . . . . . . . . . . . . . 1 General advantages of using FEPI . . . . . . . . . . . . . . . . . . 1

Advantages over alternative solutions . . . . . . . . . . . . . . . . 1 How FEPI fits into your system . . . . . . . . . . . . . . . . . . . 2 FEPI terms and concepts . . . . . . . . . . . . . . . . . . . . . 2 FEPI functions and services . . . . . . . . . . . . . . . . . . . . 3

Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Programming commands . . . . . . . . . . . . . . . . . . . . 4 Setup and resources . . . . . . . . . . . . . . . . . . . . . . 5 CICS FEPI application programs . . . . . . . . . . . . . . . . . . 6 Terminals supported . . . . . . . . . . . . . . . . . . . . . . 7 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Additional functions . . . . . . . . . . . . . . . . . . . . . . . 7

Chapter 2. Planning for FEPI . . . . . . . . . . . . . . . . . . . 9 Analysis and planning . . . . . . . . . . . . . . . . . . . . . . . 9

Back-end applications and systems . . . . . . . . . . . . . . . . . 9 Names of nodes and targets . . . . . . . . . . . . . . . . . . . 9 Operator control requirements . . . . . . . . . . . . . . . . . . 10 Signon and signoff procedures . . . . . . . . . . . . . . . . . . 10 Special event handling . . . . . . . . . . . . . . . . . . . . . 10 Using pools for control reasons . . . . . . . . . . . . . . . . . . 10 Using pools for functional reasons . . . . . . . . . . . . . . . . . 11 Number of nodes . . . . . . . . . . . . . . . . . . . . . . . 11 Setup program organization . . . . . . . . . . . . . . . . . . . 11

Organizing your pools and property sets . . . . . . . . . . . . . . . 11 Organizing pools . . . . . . . . . . . . . . . . . . . . . . . 11 Organizing property sets . . . . . . . . . . . . . . . . . . . . 12

Workload balancing in a sysplex . . . . . . . . . . . . . . . . . . 13 Planning FEPI storage . . . . . . . . . . . . . . . . . . . . . . 13

Chapter 3. Installing FEPI . . . . . . . . . . . . . . . . . . . . 15 Hardware and software requirements . . . . . . . . . . . . . . . . . 15 Updating resource definitions . . . . . . . . . . . . . . . . . . . . 15

Defining FEPI . . . . . . . . . . . . . . . . . . . . . . . . 16 Verifying that FEPI has been installed correctly . . . . . . . . . . . . . 16

Installation verification procedure: part 1 . . . . . . . . . . . . . . 16 Installation verification procedure: part 2 . . . . . . . . . . . . . . 19 Installation verification procedure: part 3 . . . . . . . . . . . . . . 21

Chapter 4. Configuring FEPI . . . . . . . . . . . . . . . . . . . 23 Defining FEPI applications to CICS . . . . . . . . . . . . . . . . . 23

Copyright IBM Corp. 1999, 2008 iii

Configuring Communications Server . . . . . . . . . . . . . . . . . 23 Availability of network resources . . . . . . . . . . . . . . . . . 24

Defining FEPI nodes to VTAM . . . . . . . . . . . . . . . . . . . 24 Back-end system configuration . . . . . . . . . . . . . . . . . . . 25

CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 IMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Writing FEPI configuration programs . . . . . . . . . . . . . . . . . 26 Writing setup programs . . . . . . . . . . . . . . . . . . . . . 26 Running setup programs . . . . . . . . . . . . . . . . . . . . 27 Varying the resources installed by the setup program . . . . . . . . . . 27 Sample FEPI configuration . . . . . . . . . . . . . . . . . . . 28 Sample lists . . . . . . . . . . . . . . . . . . . . . . . . . 29 Sample definitions . . . . . . . . . . . . . . . . . . . . . . . 30 Writing monitoring programs . . . . . . . . . . . . . . . . . . . 30 Writing operator transactions . . . . . . . . . . . . . . . . . . . 34 Writing other functions . . . . . . . . . . . . . . . . . . . . . 34

Writing global user exit programs . . . . . . . . . . . . . . . . . . 35

Chapter 5. FEPI operation . . . . . . . . . . . . . . . . . . . . 37 Controlling FEPI resources . . . . . . . . . . . . . . . . . . . . 37

SERVSTATUS . . . . . . . . . . . . . . . . . . . . . . . . 37 ACQSTATUS . . . . . . . . . . . . . . . . . . . . . . . . 37 LASTACQCODE . . . . . . . . . . . . . . . . . . . . . . . 38 INSTLSTATUS . . . . . . . . . . . . . . . . . . . . . . . . 38 WAITCONVNUM . . . . . . . . . . . . . . . . . . . . . . . 38 STATE . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Performance . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Normal shutdown . . . . . . . . . . . . . . . . . . . . . . . 39 Immediate shutdown . . . . . . . . . . . . . . . . . . . . . . 40 Forced shutdown . . . . . . . . . . . . . . . . . . . . . . . 40

Using FEPI with XRF . . . . . . . . . . . . . . . . . . . . . . 40 XRF and VTAM . . . . . . . . . . . . . . . . . . . . . . . . 40 FEPI resource definition and XRF . . . . . . . . . . . . . . . . . 40 XRF takeover of front-end system . . . . . . . . . . . . . . . . . 41 XRF takeover of back-end system . . . . . . . . . . . . . . . . . 42

Using FEPI with VTAM persistent sessions . . . . . . . . . . . . . . 43 Restart of front-end system using persistent sessions . . . . . . . . . . 43 Restart of back-end system using persistent sessions . . . . . . . . . 43

Chapter 6. The FEPI user exit . . . . . . . . . . . . . . . . . . . 47 How to use the user exit . . . . . . . . . . . . . . . . . . . . . 47 Implementation in C . . . . . . . . . . . . . . . . . . . . . . . 47 Standard definitions and data types . . . . . . . . . . . . . . . . . 47 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Standard header structure . . . . . . . . . . . . . . . . . . . . . 48 FEPI Send/Receive data conversion user exit (UE109031) . . . . . . . . . 49

Function prototype . . . . . . . . . . . . . . . . . . . . . . 49 Exit-specific constants . . . . . . . . . . . . . . . . . . . . . 49 Exit-specific structure . . . . . . . . . . . . . . . . . . . . . 49 Fields in exit-specific structure . . . . . . . . . . . . . . . . . . 50 Return codes . . . . . . . . . . . . . . . . . . . . . . . . 51

Chapter 7. Problem determination . . . . . . . . . . . . . . . . . 53 Debugging FEPI applications . . . . . . . . . . . . . . . . . . . . 53 FEPI dump . . . . . . . . . . . . . . . . . . . . . . . . . . 53

iv TXSeries for Multiplatforms: Front-End Programming Interface for Windows

FEPI trace . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Taking trace entries . . . . . . . . . . . . . . . . . . . . . . 53 Interpreting FEPI trace entries . . . . . . . . . . . . . . . . . . 53 Using IBM Communications Server for Windows trace . . . . . . . . . 53

FEPI messages . . . . . . . . . . . . . . . . . . . . . . . . 54 Reporting a FEPI problem to IBM . . . . . . . . . . . . . . . . . . 54

Chapter 8. Basics of FEPI programming . . . . . . . . . . . . . . . 55 Communication and conversations . . . . . . . . . . . . . . . . . . 55 Structure and design . . . . . . . . . . . . . . . . . . . . . . . 56

Programming . . . . . . . . . . . . . . . . . . . . . . . . 56

Chapter 9. Data-stream applications . . . . . . . . . . . . . . . . 59 General sequence of commands . . . . . . . . . . . . . . . . . . 59 Receiving . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Command completion . . . . . . . . . . . . . . . . . . . . . 60 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Sending . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

CONVERSE . . . . . . . . . . . . . . . . . . . . . . . . . . 63 SLU P mode samples . . . . . . . . . . . . . . . . . . . . . . 63

Chapter 10. Application design . . . . . . . . . . . . . . . . . . 65 Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Access programs . . . . . . . . . . . . . . . . . . . . . . . 65 Begin-session handler . . . . . . . . . . . . . . . . . . . . . 66 Unsolicited-data handler . . . . . . . . . . . . . . . . . . . . 66 End-session handler . . . . . . . . . . . . . . . . . . . . . . 67

Application organization . . . . . . . . . . . . . . . . . . . . . 67 Application style . . . . . . . . . . . . . . . . . . . . . . . 67 Started tasks . . . . . . . . . . . . . . . . . . . . . . . . 68 Conversations . . . . . . . . . . . . . . . . . . . . . . . . 69

Error handling . . . . . . . . . . . . . . . . . . . . . . . . . 71 Timeouts . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Lost session . . . . . . . . . . . . . . . . . . . . . . . . . 72 Previous SEND failed . . . . . . . . . . . . . . . . . . . . . 72 Communications errors . . . . . . . . . . . . . . . . . . . . . 73 Bypass by user exit . . . . . . . . . . . . . . . . . . . . . . 73 Unknown conversation ID . . . . . . . . . . . . . . . . . . . . 73 Operator/system action . . . . . . . . . . . . . . . . . . . . . 73 Shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . 73

System considerations . . . . . . . . . . . . . . . . . . . . . . 74 IMS considerations . . . . . . . . . . . . . . . . . . . . . . 74 Performance . . . . . . . . . . . . . . . . . . . . . . . . . 76

Chapter 11. Specialized functions . . . . . . . . . . . . . . . . . 77 Set and test sequence number (STSN) . . . . . . . . . . . . . . . . 77 DRx responses . . . . . . . . . . . . . . . . . . . . . . . . . 77 SNA commands . . . . . . . . . . . . . . . . . . . . . . . . 78

Chapter 12. Sample programs . . . . . . . . . . . . . . . . . . 79 Sample programs for CICS for Windows . . . . . . . . . . . . . . . 79 Installing the CICS front-end samples . . . . . . . . . . . . . . . . 80 Using the samples . . . . . . . . . . . . . . . . . . . . . . . 80

The back-end CICS program . . . . . . . . . . . . . . . . . . . 81 The back-end IMS program . . . . . . . . . . . . . . . . . . . 82

Contents v

Description of the samples . . . . . . . . . . . . . . . . . . . . 83 Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Monitor and unsolicited-data handler . . . . . . . . . . . . . . . . 84 Begin session . . . . . . . . . . . . . . . . . . . . . . . . 85 End-session handler . . . . . . . . . . . . . . . . . . . . . . 86 SLU P one-out one-in . . . . . . . . . . . . . . . . . . . . . 87 SLU P pseudoconversational . . . . . . . . . . . . . . . . . . . 88 STSN handler . . . . . . . . . . . . . . . . . . . . . . . . 90

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Trademarks and service marks . . . . . . . . . . . . . . . . . . . 92

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

vi TXSeries for Multiplatforms: Front-End Programming Interface for Windows

Figures 1. Structure of FEPI and application programs . . . . . . . . . . . . . . . . . . . . . 2 2. CECI transaction: initial screen . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3. CECI: choice of FEPI command . . . . . . . . . . . . . . . . . . . . . . . . . 17 4. CECI: about to execute FEPI AP command . . . . . . . . . . . . . . . . . . . . . 17 5. CECI: execution of FEPI AP command complete . . . . . . . . . . . . . . . . . . . 17 6. CECI FEPI AP transaction completed . . . . . . . . . . . . . . . . . . . . . . . 18 7. CECI: about to execute FEPI ALLOCATE command . . . . . . . . . . . . . . . . . . 18 8. CECI: execution of FEPI ALLOCATE command complete . . . . . . . . . . . . . . . . 18 9. CECI FEPI ALLOCATE transaction completed . . . . . . . . . . . . . . . . . . . . 18 10. CECI: about to execute FEPI INSTALL PROPERTYSET command . . . . . . . . . . . . 19 11. CECI: execution of FEPI INSTALL PROPERTYSET command complete . . . . . . . . . . 19 12. CEMT INQ transaction: initial screen . . . . . . . . . . . . . . . . . . . . . . . 20 13. CEMT INQ FEPROPSET: results screen . . . . . . . . . . . . . . . . . . . . . . 20 14. CEMT INQ FEPROPSET ENTRY DISCARDED . . . . . . . . . . . . . . . . . . . 21 15. CEMT INQ FEPROPSET transaction completed . . . . . . . . . . . . . . . . . . . 21 16. The sample FEPI configuration: a diagrammatic representation . . . . . . . . . . . . . . 29 17. CZBC transaction: customer inquiry . . . . . . . . . . . . . . . . . . . . . . . . 81 18. CZPS transaction: SLU P sample program . . . . . . . . . . . . . . . . . . . . . 88 19. CZPA transaction: SLU P pseudoconversational sample program . . . . . . . . . . . . . 89

Copyright IBM Corp. 1999, 2008 vii

viii TXSeries for Multiplatforms: Front-End Programming Interface for Windows

Tables 1. Conventions that are used in this book . . . . . . . . . . . . . . . . . . . . . . . xii 2. A sample FEPI configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 29 3. ENDSTATUS values and associated meanings for data stream . . . . . . . . . . . . . . 61 4. Sample programs for CICS for Windows and their names . . . . . . . . . . . . . . . . 79 5. Functional cross-reference for sample programs . . . . . . . . . . . . . . . . . . . 79

Copyright IBM Corp. 1999, 2008 ix

x TXSeries for Multiplatforms: Front-End Programming Interface for Windows

About this book This book describes the Front-End Programming Interface (FEPI). An integral part of the Customer Information and Control System (CICS) component of TXSeries running on Windows, FEPI enables the writing and administration of CICS application programs that access other CICS or Information Management System (IMS) programs. FEPI provides a front end to those programs by simulating the terminals that they use.

Who should read this book This document provides information for CICS system administrators who are responsible for installing and configuring FEPI, and for application programmers who are responsible for writing FEPI front-end application programs.

FEPI applications can be written in the C, C++, and COBOL programming languages.

Users of this document need to be familiar with the following: v All aspects of CICS administration v The IBM ACF/VTAM telecommunications access method v The CICS administration and programming interfaces v If you are accessing IMS back-end systems: the use of IBM Information

Management System/Virtual Storage (IMS/VS) or IBM Information Management Systems/Enterprise Systems Architecture (IMS/ESA) and writing IMS applications

v If you are writing FEPI applications: data communication and protocols

To configure FEPI, you need to be familiar with all aspects of CICS administration as described in the CICS documentation that is listed in Related Information on page xii.

Document organization This document is organized as follows: v Chapter 1, Introducing FEPI, on page 1 provides an introduction to FEPI. It

discusses its relationship to other CICS components and introduces FEPI terms, concepts, functions, and services.

v Chapter 2, Planning for FEPI, on page 9 discusses planning for FEPI. v Chapter 3, Installing FEPI, on page 15 discusses FEPI installation. v Chapter 4, Configuring FEPI, on page 23 discusses FEPI configuration. v Chapter 5, FEPI operation, on page 37 discusses how to control FEPI

resources, performance, and shutdown. v Chapter 6, The FEPI user exit, on page 47 discusses how to use the FEPI

global user exit. v Chapter 7, Problem determination, on page 53 discusses how to identify the

source of errors that affect FEPI applications. v Chapter 8, Basics of FEPI programming, on page 55 introduces the basic

commands that are used in FEPI programming. v Chapter 9, Data-stream applications, on page 59 discusses the low-level

data-stream interface for FEPI applications.

Copyright IBM Corp. 1999, 2008 xi

v Chapter 10, Application design, on page 65 discusses the basic design of FEPI applications.

v Chapter 11, Specialized functions, on page 77 describes specialized control functions that are handled by FEPI but can be taken over by a FEPI application.

v Chapter 12, Sample programs, on page 79 discusses the sample programs that are provided with FEPI.

Related Information For further information about the topics that are discussed in this document, see the following documents: v TXSeries for Multiplatforms Administration Guide v TXSeries for Multiplatforms Administration Reference v TXSeries for Multiplatforms Application Programming Guide v TXSeries for Multiplatforms Application Programming Reference v Documentation for the communications systems and mainframe back ends that

are used with FEPI.

Conventions used in this book TXSeries for Multiplatforms documentation uses the following typographical and keying conventions.

Table 1. Conventions that are used in this book Convention Meaning Bold Indicates values that you must use literally, such as commands,

functions, and resource definition attributes and their values. When referring to graphical user interfaces (GUIs), bold also indicates menus, menu items, labels, buttons, icons, and folders.

Monospace Indicates text that you must enter at a command prompt. Monospace also indicates screen text and code examples.

Italics Indicates variable values that you must provide (for example, you supply the name of a file for file_name). Italics also indicates emphasis and the titles of books.

< > Encloses the names of keys on the keyboard. Where x is the name of a key, indicates a control-character

sequence. For example, means hold down the Ctrl key while you press the c key.

Refers to the key labeled with the word Return, the word Enter, or the left arrow.

% Represents the UNIX command-shell prompt for a command that does not require root privileges.

# Represents the UNIX command-shell prompt for a command that requires root privileges.

C:\> Represents the Windows command prompt. > When used to describe a menu, shows a series of menu selections.

For example, Select File > New means From the File menu, select the New command.

xii TXSeries for Multiplatforms: Front-End Programming Interface for Windows

Table 1. Conventions that are used in this book (continued) Convention Meaning Entering commands When instructed to enter or issue a command, type the command

and then press . For example, the instruction Enter the ls command means type ls at a command prompt and then press .

[ ] Encloses optional items in syntax descriptions. { } Encloses lists from which you must choose an item in syntax

descriptions. | Separates items in a list of choices enclosed in { } (braces) in syntax

descriptions. ... Ellipses in syntax descriptions indicate that you can repeat the

preceding item one or more times. Ellipses in examples indicate that information was omitted from the example for the sake of brevity.

IN In function descriptions, indicates parameters whose values are used to pass data to the function. These parameters are not used to return modified data to the calling routine. (Do not include the IN declaration in your code.)

OUT In function descriptions, indicates parameters whose values are used to return modified data to the calling routine. These parameters are not used to pass data to the function. (Do not include the OUT declaration in your code.)

INOUT In function descriptions, indicates parameters whose values are passed to the function, modified by the function, and returned to the calling routine. These parameters serve as both IN and OUT parameters. (Do not include the INOUT declaration in your code.)

$CICS Indicates the full path name of the location in which the CICS product is installed; for example, /usr/lpp/cics on AIX. If the CICS environment variable is set to the product path name, you can use the examples exactly as shown in this book; otherwise, you must replace all instances of $CICS with the CICS product path name.

CICS on Open Systems

Refers collectively to the CICS product for all supported UNIX platforms.

TXSeries for Multiplatforms

Refers collectively to the CICS for AIX, CICS for HP-UX, CICS for Solaris, and CICS for Windows products.

CICS Refers generically to the CICS for AIX, CICS for HP-UX, CICS for Solaris, and CICS for Windows products. Other CICS products in the CICS Family are distinguished by their operating system (for example, IBM mainframe-based CICS for the z/OS platform).

How to send your comments Your feedback is important in helping to provide the most accurate and highest quality information. If you have any comments about this book or any other TXSeries documentation, send your comments by e-mail to [email protected]. Be sure to include the name of the book, the document number of the book, the version of TXSeries, and, if applicable, the specific location of the information you are commenting on (for example, a page number or table number).

About this book xiii

xiv TXSeries for Multiplatforms: Front-End Programming Interface for Windows

Chapter 1. Introducing FEPI The CICS Front End Programming Interface (FEPI) is an integral part of CICS. FEPI provides access, by way of simulated terminals, to CICS and Information Management Systems (IMS) applications that are available through a communications network. FEPI enables you to write CICS application programs that access other CICS or IMS applications.

This chapter provides an overview of FEPI. It discusses the advantages of using FEPI and shows its relationship to other components of CICS systems. It also introduces basic terms and concepts that are related to FEPI, and summarizes the functions and services that are provided for administration and programming.

General advantages of using FEPI FEPI applications can extend the scope of existing CICS and IMS applications by providing a simple integrated interface to these programs. This interface enables the use of these programs in different combinations, in different environments, or on different systems, without their needing to be changed.

Existing applications cannot be changed for may reasons; for example, the source can be unavailable or difficult to modify, or perhaps the application must continue to work with IBM 3270 information display systems while its function is extended or used with another system.

Without changing the existing program, you can use FEPI to provide a front-end program that simulates a terminal and gains access to applications that are written to support that terminal. That program can then use the existing applications with the existing applications, unaware that anything has changed. Changes in function in the simulating program enable the existing application to be used differently. For example, newly written applications can collect data from several existing applications. The existing applications can be on the same system as is the simulating program, or on a different system.

Advantages over alternative solutions Using FEPI is preferable to other methods of accessing existing programs. Using CICS intersystem communication (ISC) or multiregion operation (MRO) to access remote applications

Using ISC or MRO can often require some changes to the existing application programs; for example, to change the type of terminal that is supported, or to provide an interface that uses a communication area.

Using CICS transaction routing over ISC or MRO can avoid the need for changes to be made to the existing application programs. However, it prevents access to IMS applications.

Using native communications support Programmers can write an access program to issue calls to the underlying communications server; for example, VTAM for CICS/ESA. But these calls cannot be part of a CICS application program.

Copyright IBM Corp. 1999, 2008 1

How FEPI fits into your system Figure 1 shows the relationship between FEPI and other components of your system. Note, particularly, the unchanged applications in the lower part of the figure, and the new CICS FEPI application near the top. To an existing application, the front-end application looks like a terminal.

FEPI terms and concepts This section explains important terms and concepts in FEPI and, where appropriate, distinguishes between their usage in FEPI, CICS, IMS, and VTAM: application

FEPI uses application in the usual sense of a program or suite of programs that do work. A CICS FEPI application is a CICS application that is designed to use FEPI to communicate with existing back-end applications. It is also known as a terminal front-end program. VTAM uses application for programs that communicate directly by using VTAM; in a FEPI environment, this means the back-end systems on one hand, and FEPI on the other.

setupfunction

newapplication

3270 3270

UNCHANGEDapplication B

Conceptualdata flow

Key:

User-suppliedprogram

IBM-suppliedprogram

CICS

CICS FEPI

VTAM/Communications Server

Simulatedterminals

front end

back end

VTAM

CICS

VTAM

IMS

UNCHANGEDapplication A

Figure 1. Structure of FEPI and application programs

2 TXSeries for Multiplatforms: Front-End Programming Interface for Windows

conversation A FEPI conversation is not the same as an IMS conversation, although they would normally coincide, and it is not related to CICS conversational mode. It is analogous to a CICS APPC conversation.

front end, back end The term front end refers to the system on which the CICS FEPI application runs; the term back end refers to the system on which the existing CICS or IMS applications run. This term is equivalent to the term partner system that is used elsewhere by CICS. (The front end and the back end can be the same system.)

inbound, input These terms describe data that is received by a program from elsewhere. From the point-of-view of the back-end system, this data is outbound or output to a terminal.

message VTAM and IMS use message to refer to any data transmission; that is, not only to data that is displayed for a users attention.

node In VTAM and IMS, a node is a named point in a network. In FEPI, nodes are those points (VTAM nodes for CICS/ESA, Communications Server Logical Unit Applications for CICS for OS/2) that are the secondary LU terminals that are simulated by FEPI.

outbound, output These terms describe data that is sent by the FEPI application to the back-end application. From the point-of-view of the back-end system, this data is inbound or input from a terminal.

secondary In VTAM, secondary describes one of the partners of an LU-LU pair; the terminals that are simulated by FEPI are secondary LUs. This is not the same as the CICS usage of secondary.

VTAM, IMS, CICS/ESA VTAM refers to ACF/VTAM, and IMS refers to IMS/VS and IMS/ESA. Information that refers to CICS/ESA also applies to the CICS Transaction Server for OS/390.

FEPI functions and services This section provides general information about functions and services that are provided in FEPI.

FEPI functions can be invoked only through the FEPI programming interface, which is an extension to the EXEC CICS programming interface. All FEPI requests are made by issuing EXEC CICS FEPI commands; all the commands have the qualifier FEPI. For educational and initial development purposes, you can simply use CECI, instead of formally writing a program.

All functions are available in the normal way to all applications, except that some functions are intended for system administrators, and their use can be restricted. All the other facilities that you can use with CICS applications, such as the execution diagnostic facility (EDF) and the command interpreter transaction, CECI, are available.

Chapter 1. Introducing FEPI 3

Samples To help you develop CICS FEPI applications, and to show FEPI functions, FEPI includes detailed samples. They form an integrated set and include a program that sets up the FEPI configuration that is needed in order to run the other samples. The samples are supplied in source format, and are in the directory c:\opt\TXSeries\cics\src\samples\FEPI. See Chapter 12, Sample programs, on page 79.

Programming commands EXEC CICS FEPI commands provide several ways of developing CICS FEPI applications. FEPI on CICS for Windows provides the data-stream and specialized logical levels of programming commands.

Note: The high-level programming interface, which consists of the key stroke and screen image (formatted data) interfaces, do not apply to FEPI on CICS for Windows. The high-level programming interface is used with FEPI on other platforms

Data-stream level: For use with IMS SLU P applications and more complicated 3270 applications.

Specialized level: For access to complex VTAM communication functions and events. Designed for use by vendors and experienced CICS FEPI application developers.

Data-stream-level commands FEPI data-stream-level commands give an application complete control of the 3270 data stream. These commands are also needed for SLU P applications, which can use only this interface. FEPI does not buffer or interpret the data stream; it is presented as it arrives from the back-end application, and the front-end application must be prepared to handle whatever is presented. Similarly, data that is sent by the front-end application is transmitted without verification.

A detailed knowledge of data communication and protocols and of data-stream format is required.

See Chapter 9, Data-stream applications, on page 59 for details.

Specialized-level commands These are some of the specialized functions that can be accessed through FEPI: STSN for SLU P applications:

Set and test sequence number (STSN) is a communications protocol that checks and controls transmissions. FEPI normally handles all necessary STSN processing automatically. However, FEPI also provides access to STSN information for those applications that need to control sequence number data.

Application access to definite responses: When a flow is received, the receiving LU can choose what response to return to the sending LU. FEPI normally handles this automatically, but also provides facilities for applications to determine this flow.


Other VTAM facilities: Some back-end applications use a VTAM facility known as CLSDST(PASS); this can be used in more sophisticated CICS FEPI application programming.

For more information, see Handling CLSDST(PASS) on page 33.

See Chapter 11, Specialized functions, on page 77 for details.

List of commands The EXEC CICS FEPI application programming commands are: ALLOCATE

Establishes communication with a back-end application. FREE Frees communication with a back-end application. SEND Sends data from a CICS FEPI application to a back-end application. RECEIVE

Receives data into a CICS FEPI application from a back-end application. CONVERSE

Sends data to, and receives data from, a back-end application. ISSUE Sends control data to a back-end application. EXTRACT

Gets field data and attributes, set-and-test-sequence-number (STSN) data, or conversation status.

START Schedules a CICS transaction to handle inbound data.

Setup and resources In addition to the application programming functions that communicate with back-end applications, FEPI also provides administrative functions that define and inquire about FEPI resources and perform control operations. The setup program contains the functions to define and configure FEPI resources. The EXEC CICS FEPI commands that provide these functions are: INSTALL, ADD

Sets up communication resources. DISCARD, DELETE

Discards communication resources. INQUIRE

Queries FEPI resource status. SET Controls FEPI resources.

The setup functions are usually performed by a customer-written transaction that is defined in the StartupProgList attribute of the Region Definitions for CICS for Windows. See Running setup programs on page 27.

As with other CICS resources, the CEMT SET and INQUIRE functions can be used to control FEPI resources, see the TXSeries for Multiplatforms Administration Reference for more information.


FEPI resources Four types of FEPI resource are available: pool, property set, target, and node. The relationship between them is described in this section. The resources are further explained in Chapter 4, Configuring FEPI, on page 23, and the more complex relationships that are possible between them are shown in Sample FEPI configuration on page 28. Pool A collection of nodes and targets. Property set

Defines the characteristics of a pool. Target Back-end systems. Node Simulated terminals.

A FEPI pool can have one or more nodes and one or more targets. The same nodes and targets can be in any number of pools, except that the same node-target pair (a connection) cannot occur in more than one pool.

A CICS FEPI application can reach a target only by specifying a pool, which defines the set of nodes that can be used to make the connection and the characteristics of the communications.

A target and an open node that are in the same pool are connected; when bound, they are in session. To bind means to establish a session on a connection, to make it ready to allow communications.

The process of communicating with a back-end system is called a conversation; it is the fundamental entity that a FEPI application handles. Only one conversation can use a connection at one time, although any number can do so consecutively. For efficiency, the session on the connection is kept bound between conversations, unless you choose otherwise. Furthermore, a conversation is owned by the task that establishes it; no other task can use it.

Note: The use of the term conversation does not mean that the back-end or front-end application must be conversational in the CICS meaning of the term.

CICS FEPI application programs A CICS FEPI application comprises several distinct logical functions: Access programs:

Communicate with the back-end applications. Begin-session handler:

Handles begin-session processing. End-session handler:

Handles end-session processing. STSN handler:

Assists message synchronization. Unsolicited-data handler:

Handles unsolicited inbound data. Monitor:

Handles unexpected events such as the loss of a session or errors in setup.


These functions can be in separate programs or contained in one program. The need for each function depends on the requirements of the application; in many cases, default processing is all that you need. Several styles of each function can be necessary, again depending on the requirements of your application.

The application programmer always writes the access programs. The system administrator usually writes the monitors to handle the unexpected events that FEPI reports to transient data queues such as CSZX. As for the other functions, sometimes the system administrator writes them, providing, perhaps, only one instance of each, so that they are common to everyone. (This approach has the advantage that adherence to standard procedures, for such things as signon and signoff, is enforced.) In other installations, the application programmer provides them.

In many cases, writing a CICS FEPI application is straightforward. However, some applications need more sophisticated programming. The programmer not only has to understand all the displays and protocols of the back-end application and system (CICS or IMS), but must also understand the detailed data-stream protocols. For further information, see Chapter 10, Application design, on page 65.

Terminals supported FEPI uses the secondary logical unit (SLU) support that is provided by the IBM Communications Server so that CICS FEPI applications can simulate particular logical unit types.

FEPI on CICS for Windows supports SLU P for a family of programmable terminals, including the 4700, accessed through an LU 0 protocol, for IMS applications. This protocol is defined in the IMS/VS Programming Guide for Remote SNA Systems (for IMS/VS Version 2) or the IMS/ESA Customization Guide (for IMS/ESA Version 3 and later). The SLU2 mode is not supported in FEPI on CICS for Windows; it is supported in FEPI on other platforms.

Data-stream-level and specialized-level commands can be used with the SLU P mode. The mode and data type are controlled by the pool that is set up by the system administrator.

These terminals are supported only when they are used to communicate with CICS or IMS systems.

Security Because FEPI is a terminal emulator, the back-end system sees the front-end as a terminal instead of as a system; it cannot differentiate between FEPI emulation and a real device. Therefore, bind, link, and attach-time security are not applicable to FEPI connections. If security is enabled in the back-end system, in order for your FEPI application to access protected resources, the emulated terminal must be signed on to the back-end.

Additional functions v To determine the source of an error, you use debugging tools, trace, dump

routines, and messages. These topics are described in Chapter 7, Problem determination, on page 53.

v The CICS FEPI global user exit is described in Chapter 6, The FEPI user exit, on page 47.


v CICS monitoring and statistics data can be used to tune FEPI applications and to control the resources that they use. For details, see the TXSeries for Multiplatforms Administration Reference.


Chapter 2. Planning for FEPI This chapter describes how to plan your system and FEPI configuration. To understand it, you need to be familiar with the basic FEPI concepts and terminology that are described in Chapter 1, Introducing FEPI, on page 1. You must also be familiar with all aspects of CICS administration and operations; if you plan to use Information Management Systems (IMS), you also need to be familiar with IMS administration and operations.

Analysis and planning First, you need to consider the following: v Details of the back-end applications and systems v Names of nodes and targets v Operator control requirements v Signon and signoff procedures v Special event handling v Pools that are required for control reasons v Pools that are required for functional reasons v Number of nodes v Setup program organization

Then you can decide how to organize your pools, their properties, and the connections.

Back-end applications and systems You need to know whether the back-end systems are CICS or IMS, the terminal types that they use, and the timing and volume of transactions that are expected. Also, do any restrictions exist for the use of the terminals? For example: v Is a specific terminal required, or can any terminal be used? v Is a specific LU or terminal type defined in the target application; for example, a

3278 model 3?

Names of nodes and targets Nodes

Decide which node names are available for use by FEPI as simulated terminals. Remember that for CICS for Windows, FEPI nodes are Communications Server Logical Unit Applications (LUAs).

Do not use names that start with the following prefixes: DFH, FAA, or ERZ. Targets

The back-end system already has defined VTAM primary PLU names (applids) that you must use. However, you can define your own local target names to associate with these applids. This means that FEPI applications are not affected if an applid is changed; you simply associate the local name with the new back-end target name.

Do not use names that start with the prefixes DFH or FAA or ERZ.


Operator control requirements The CEMT INQUIRE and SET master terminal transactions can be used to view and amend the state of FEPI resources. The CEMT DISCARD transaction can be used to remove resources from FEPI. How to use these transactions is described in the TXSeries for Multiplatforms Administration Reference. If you decide that you need extra functions for operators, you will need to write appropriate programs.

Signon and signoff procedures You need to know whether any specific requirements exist for signon and signoff to back-end systems. Consider whether central control is required, or whether applications can perform signon and signoff individually.

Special event handling In addition to signon and signoff, you need to consider what needs to be done in the following conditions, and whether these conditions are to be handled by central functions or by applications individually: v The receipt of unsolicited data v Unexpected events v Beginning a session v Ending a conversation or session v Shutdown of the front-end CICS system

If some type of enforcement is required, or if you want central provision for convenience, commonality, or the upholding of conventions and standards, you must supply a set of standard handlers. Otherwise, the application programs must handle each event.

If you need special processing when conversations and sessions are ended during CICS shutdown, you must supply an end-session handler.

Unexpected events (including errors in setup) are reported to a transient data (TD) queue so that a monitoring transaction can be triggered to handle them; they also send a message to the FEPI message log CSZL. You must decide how to handle these events, and which queues to use.

For more detailed information about the design and structure of applications, including information about using the various event handlers, see Chapter 10, Application design, on page 65.

Using pools for control reasons You can use pools for several control purposes. For example, you can define them to: v Restrict users and applications to particular targets or nodes, or restrict access to

some targets to particular times of day. v Force specific begin-session and end-session effects. v Split resources among different types of back-end requests, in accordance with

(for example) priority, or with the department that is issuing the request. By doing this, you can ensure that a set of connections is always available to a target for time-sensitive requests, while other connections handle long-running requests that are not time sensitive.

v Ration the use of connections, especially for long-running requests, so that each set of users has access to only a limited number of connections.


v Ease signon considerations.

Using pools for functional reasons Pools determine the data format and special event handlers that are used by your FEPI applications. These attributes can be specified by the application programmer, or they can be imposed by the system administrator for central control, especially of signon and signoff.

If you need several types of special event handling, you possibly need to define your own pool-specific transient data queues, in addition to the default queues.

Number of nodes The number of nodes that are required depends on: v How the pools are structured v How much storage is available v How many concurrent sessions are required to a particular target

The number of concurrent sessions to a particular target can depend on the volumes of data that are to be transmitted and the speed of the network.

Although a node can have only one session with a particular target at a time, it can communicate with several different targets concurrently, and several nodes can communicate with the same target concurrently.

Setup program organization You must decide: v How many programs you need; for example, whether your setup program

consists of a single module or a set of related modules. v Whether your programs takes replaceable parameters or fixed values. (You can

use mainly fixed programs, with a flexible program for on-off changes.) v When programs are to be run; that is, started by a transaction that is defined in

the StartupProgList attribute of the Region Definitions for CICS on Windows, run under operator control, or run at set times of the day.

v Where the definitions that are required by the setup program are to be obtained; that is, from a panel entry, from a file, or by other ways.

Organizing your pools and property sets When you have done the analysis work that is described in the previous section, you can decide how to organize your pools, their properties, and the connections between nodes and targets.

Organizing pools You can organize your pools in several ways: v If possible, restrict each pool to a single target, but specify as many nodes as

you think you need to satisfy concurrent access to the target. The reasons for taking this approach are: It avoids the need for the front-end application to specify a target. It makes it easier to avoid duplicate connection definitions. Because a connection is created for every node-target combination within a

pool, having large numbers of both nodes and targets within the same pool can generate more resources than are actually required.

Chapter 2. Planning for FEPI 11

The overhead that is associated with a pool is very small. Therefore, you can define many pools.

The expected concurrent usage of each target can be different. If you have more than one target in the pool, it becomes difficult to estimate the number of nodes that are required.

v You can define a pool that contains only one node and one target. This lets a FEPI application allocate a specific session, which is necessary if the target system associates any special qualities with a particular terminal ID.

v You can define pools that use different nodes to reference the same target. By making each pool available to a different group of users, you can eliminate competition for resources. Alternatively, you can use each pool to support a different set of properties, in accordance with application requirements.

v If you plan to use the VTAM CLSDST(PASS) command, other considerations possibly apply. See Handling CLSDST(PASS) on page 33.

Do not use names starting with DFH or FAA or ERZ for pools.

Organizing property sets By using property sets, you can define the properties of pools (such as the data format and special functions that they use) separately from the definition of the pool itself. You can use a single property set to define any number of pools. You must define as many property sets as you need to satisfy every unique pool requirement. Because the overhead that is associated with a property set is very small, you can define many of them.

The properties are: Device attributes

This specifies to which family the simulated terminal belongs, SLU2 or SLU P. Many back-end applications can be run with any terminal type, so you can use

the default device type (SLU2, 3278 model 2). But if you have applications that demand particular terminal types, you need to define pools with the appropriate device types.

Data handling This specifies which command level to use (high-level with formatted data, or data-stream), how much data can be handled, and how contention is to be handled.

Applications that require sophisticated functions or use SLU P, and those that perform a simple pass-through, need the data-stream level. In most cases, the default data size of 4096 is adequate; increase it only if you know that you have large amounts of data to send and receive in a single command. Set contention handling so that the front end wins, as for a real terminal, unless you have some particular reason for not doing so.

Session management This specifies whether begin-session and end-session are to be handled by special transactions, and whether initial inbound data is expected. For SLU P, it also includes whether message resynchronization (set and test sequence number (STSN)) is to be handled.

The use of event handlers was introduced in Signon and signoff procedures on page 10; it is generally preferable to use specially written transactions for session management, rather than to leave it to be handled individually by applications.


If a back-end system sends initial data (a good morning message), you must specify this as a property of the pool, so that FEPI waits for the data to arrive and ensures that the front-end application receives it; otherwise the results will be unpredictable. For SLU2, IMS always sends initial data; CICS might or might not do so, depending on your system definition. FEPI does all the necessary STSN handling automatically, but you can specify a transaction to handle it yourself.

Unexpected events This specifies how unsolicited data and other unexpected events (including setup errors) are to be handled.

General considerations of the need for transactions and queues have been discussed earlier in this section. If you choose not to handle unsolicited data in your own transaction, you can tell FEPI how to handle it for you, positively or negatively; if the back-end system is IMS, you must specify that FEPI responds positively. All unexpected events are logged in the FEPI message log (CSZL), even if you specify no unexpected event queue.

Journaling This specifies what sort of data journaling is required and which journal to use.

Do not use names that start with DFH, FAA, or ERZ for property sets.

Workload balancing in a sysplex In an MVS/ESA sysplex, you can create a CICSplex that consists of sets of functionally equivalent CICS terminal-owning regions (TORs) and application-owning regions (AORs). If the FEPI back-end system is a TOR in such a CICSplex, you can use the VTAM generic resource function to perform workload balancing across the available TORs.

A VTAM application program such as CICS can be known to VTAM by a generic resource name, and by the specific network name that is defined on its VTAM APPL definition statement. Several CICS regions can use the same generic resource name.

To start a session with a CICSplex that has several terminal-owning regions, a FEPI application names a target that you have defined as the generic resource name of the TORs. Using the generic resource name, VTAM can select one of the CICS TORs to be the target for that session. For this mechanism to operate, the TORs must all register to VTAM under the same generic resource name. VTAM can perform dynamic workload balancing of the terminal sessions across the available terminal-owning regions.

For information about defining FEPI targets as VTAM generic resource names, see the APPLLIST option of the FEPI INSTALL TARGETLIST system programming command. For further information about VTAM generic resources, see the TXSeries for Multiplatforms Intercommunication Guide and the VTAM Version 4 Release 2 Release Guide.

Planning FEPI storage FEPI does not require any additional Windows storage beyond that which is recommended for basic CICS. The basic requirement for dynamic storage is 250 KB; it is advisable to add ten percent to your estimate for contingency.

Chapter 2. Planning for FEPI 13

Chapter 3. Installing FEPI FEPI is installed automatically with CICS for Windows. For details about CICS installation, see the TXSeries for Multiplatforms Installation Guide. After installation, you can update default CICS resource definitions, initialize and start FEPI, and verify that FEPI is installed correctly.

Hardware and software requirements Front-end

v The IBM Communications Server for Windows is required for developing or running an application across connected systems or workstations.

v Extra 37x5 controllers and network control programs (NCPs) are possibly needed to provide the intersystem connections.

Back-end Applications that are running on the following, and subsequent compatible releases, are supported: v IMS/VS Version 2 Release 2 v IMS/ESA Version 3 Release 1 v IMS/ESA Version 4 v IMS/ESA Version 5 v IMS/ESA Version 6FEPI provides simulation for a family of programmable terminals, including the 4700, that are accessed through an LU0 protocol (called SLU P), for Information Management System (IMS) applications.

Updating resource definitions When CICS is installed, the transient data queues (TDQ) CXZL and CSZX that FEPI requires are defined in the CICS region by default. You can use the default definitions or create your own definitions, and you can also create any additional queues that you need. CSZL The FEPI message log. You can define CSZL as an extrapartition queue.

Note that CSZL must be defined as nonrecoverable. CSZX The queue for information about unexpected events (including setup errors)

that do not relate to specific pools. You can define CSZX as an intrapartition, extrapartition, or indirect queue. Note, however, that it must be defined as nonrecoverable.

It is recommended that you define CSZX as an intrapartition queue, with a trigger level of 1, so that each event is processed as soon as it is reported. (You must also, of course, write and install the event-handling transaction that is to be triggered.)

Any pool-specific TD queues that you require Such queues receive information about events that affect specific pools. Define them in the same way as CSZL and CSZX are defined.

When you have completed the above steps, check whether FEPI has been installed successfully by following the procedure that is given in Verifying that FEPI has been installed correctly on page 16.


Defining FEPI Do the following to define FEPI: v To specify that FEPI is available, use the TXSeries Administration Console to

define an LU0 Listener Definition (LD) and select Protocol=LU0.

Note: 1. The transaction called CLU0 is defined for you by default for FEPI to

function correctly. Do not remove this definition. 2. The IBM Communications Server is a prerequisite for using an LU0

listener.v Ensure that the transient data queues CSZL and CSZX and the transaction CLU0

are in the runtime database.

Verifying that FEPI has been installed correctly To check whether you have installed FEPI correctly, use the CICS command-level interpreter transaction, CECI. (CECI is described in the TXSeries for Multiplatforms Administration Reference.)

Note: The commands that are included in this section are designed to test the installation of FEPI, not to demonstrate its use. They are limited by what can be done before FEPI is configured.

Installation verification procedure: part 1 This part of the verification process tests whether FEPI itself has been installed successfully.

1. Ensure that you have the necessary operator authority to run CECI. 2. Start your CICS region.

3. Sign onto the CICS system. 4. Type CECI and press ENTER.

You should see:

Check whether: v FEpi appears in the list.

STATUS: ENTER ONE OF THE FOLLOWING ABend ENQ PErform SIGNOFf ADdress ENTer POp SIGNON ALlocate EXtract PUsh START ASKtime FEpi READ STARTBr ASSign FOrmattime READNext SUspend CAncel FREE READPrev SYncpoint COLlect FREEMain READQ Trace CONNect Getmain RECeive Unlock CONVerse Handle RELease WAit DELAy IGnore RESetbr WRITE DELETE INquire RETRieve WRITEQ DELETEQ ISsue RETUrn Xctl DEQ Journal REWrite DUmp LInk SENd ENDbr LOad SET PF 1 HELP 2 HEX 3 END 4 EIB 5 VAR 6 USER 9 MSG

Figure 2. CECI transaction: initial screen


||||||||

5. On the top line, type FEPI POOL (ABCD). Press ENTER. You should see:

Check whether: v The EXEC CICS FEPI options are listed as above.

6. On the top line, add AP so that it becomes FEPI AP. Press ENTER. You should see:

Check whether: v The status line shows ABOUT TO EXECUTE COMMAND. v No error messages are displayed.

(The AP command does nothing other than test whether FEPI commands can be issued.)

7. Press ENTER. You should see:

Check whether: v The status line shows COMMAND EXECUTION COMPLETE. v The response line shows RESPONSE: NORMAL.

8. Press F3.

FEPI POOL (ABCD) STATUS: ENTER ONE OF THE FOLLOWING ADd ALlocate AP Converse DElete DIscard Extract Free INQuire INStall ISsue Receive REQuest SENd SET SP STart PF 1 HELP 2 HEX 3 END 4 EIB 5 VAR 6 USER 9 MSG

Figure 3. CECI: choice of FEPI command

FEPI AP STATUS: ABOUT TO EXECUTE COMMAND NAME= EXEC CICS FEPI AP Noop PF 1 HELP 2 HEX 3 END 4 EIB 5 VAR 6 USER 7 SBH 8 SFH 9 MSG 10 SB 11 SF

Figure 4. CECI: about to execute FEPI AP command

FEPI AP STATUS: COMMAND EXECUTION COMPLETE NAME= EXEC CICS FEPI AP Noop

RESPONSE: NORMAL EIBRESP=+0000000000 PF 1 HELP 2 HEX 3 END 4 EIB 5 VAR 6 USER 7 SBH 8 SFH 9 MSG 10 SB 11 SF

Figure 5. CECI: execution of FEPI AP command complete

Chapter 3. Installing FEPI 17

You should see:

9. Press CLEAR. Type CECI FEPI ALLOCATE POOL(PPPPPPPP) TARGET(TTTTTTTT) CONVID(). Press ENTER. You should see:



Check whether: v The status line shows COMMAND EXECUTION COMPLETE. v The response line shows RESPONSE: INVREQ, which indicates an invalid

request. (The request is invalid because no pools or targets have yet been defined to FEPI. The purpose of issuing the command is to check whether the FEPI error-reporting procedures are operating correctly.)

11. Press F3. You should see:

CECI FEPI AP STATUS: SESSION ENDED

Figure 6. CECI FEPI AP transaction completed

FEPI ALLOCATE POOL (PPPPPPPP) TARGET (TTTTTTTT) STATUS: ABOUT TO EXECUTE COMMAND NAME= EXEC CICS FEpi Allocate Pool( PPPPPPPP ) Convid() < TArget( TTTTTTTT ) > < TImeout() > < SEQNUMIn() > < SEQNUMOut() > < SESsnstatus() > PF 1 HELP 2 HEX 3 END 4 EIB 5 VAR 6 USER 7 SBH 8 SFH 9 MSG 10 SB 11 SF

Figure 7. CECI: about to execute FEPI ALLOCATE command

FEPI ALLOCATE POOL(PPPPPPPP) TARGET(TTTTTTTT) CONVID() STATUS: COMMAND EXECUTION COMPLETE NAME= EXEC CICS FEpi Allocate Pool( PPPPPPPP ) Convid( ........ ) < TArget( TTTTTTTT ) > < TImeout() > < SEQNUMIn() > < SEQNUMOut() > < SESsnstatus() > RESPONSE: INVREQ EIBRESP=+0000000016 PF 1 HELP 2 HEX 3 END 4 EIB 5 VAR 6 USER 7 SBH 8 SFH 9 MSG 10 SB 11 SF

Figure 8. CECI: execution of FEPI ALLOCATE command complete

CECI FEPI ALLOCATE POOL(PPPPPPPP) TARGET(TTTTTTTT) CONVID() STATUS: SESSION ENDED

Figure 9. CECI FEPI ALLOCATE transaction completed


v The response line shows RESPONSE: NORMAL.You have successfully issued a FEPI system programming command and your ESM authorizations are correctly set.

3. Press F3. Press CLEAR. Type CEMT IN and press ENTER. You should see:

Check whether the FETarget, FENode, FEPOol, FEPRopset, and FEConnection options appear on the screen.

4. On the top line, add FEPROPSET so that it becomes INQ FEPROPSET. Press ENTER. You should see:

Check whether: v Line 3 reads Fepr(YYYYYYYY). v The response line shows RESPONSE: NORMAL. This confirms that the operator

commands are working for FEPI and that the FEPI INSTALL PROPERTYSET command that you issued in step 1 on page 19 was successful.

5. Type D at the start of Line 3, so that it becomes D Fepr(YYYYYYYY). Press ENTER. You should see:

I STATUS: ENTER ONE OF THE FOLLOWING OR HIT ENTER FOR SYSTEM PARAMETERS

AUTInstmode TClass AUXtrace TRACe DUMP TRANsaction DUMPOptions FEConnection FENode FEPOol FEPRopset FETarget FIle TDqueue TErminal Netname Program TAsk APPLID=region7 PF 1 HELP 3 END 9 MSG

Figure 12. CEMT INQ transaction: initial screen

INQ FEPROPSET STATUS: RESULTS Fepr(YYYYYYYY) APPLID=region7 RESPONSE: NORMAL PF 1 HELP 3 END 7 SBH 8 SFH 9 MSG 10 SB 11 SF

Figure 13. CEMT INQ FEPROPSET: results screen


Check whether: v Line 3 shows ENTRY DISCARDED. v The response line shows RESPONSE: NORMAL.This resets the FEPI configuration to its initial state.

6. Press F3. You should see:

Press CLEAR. This is the end of the second part of the verification procedure.

Installation verification procedure: part 3 Look at the Transient Data Queue CSZL, by using an editor. This file is in C:\var\cics_regions\regionName\data\CSZL.out. This file should contain messages that relate to the FEPI resources that you have installed.

INQ FEPROPSET STATUS: RESULTS Fepr(YYYYYYYY) ENTRY DISCARDED APPLID=CSYSE6 RESPONSE: NORMAL PF 1 HELP 3 END 7 SBH 8 SFH 9 MSG 10 SB 11 SF

Figure 14. CEMT INQ FEPROPSET ENTRY DISCARDED

CEMT INQ FEPROPSET STATUS: SESSION ENDED

Figure 15. CEMT INQ FEPROPSET transaction completed


Chapter 4. Configuring FEPI Configuring FEPI requires that you configure the following related applications: v Communications Server v VTAM v CICS or IMS back-end systems

In addition, write the following programs for FEPI: v Required: a setup program for installing FEPI resources v If needed:

A monitoring program to handle unexpected events Transactions for operator control and administrations Common functions Global user exit programs

Defining FEPI applications to CICS Defining your FEPI applications to CICS includes the setup programs, any common functions, and any additional transient data queues that you need for handling pool-specific events.

Define transactions that are to be started by FEPI (the event handlers and pseudoconversational access programs) as CICS-started tasks. Set the Purgability attribute of the Transaction Definitions to Purgability=notpurgable. This setting prevents the transactions from being accidentally canceled by CICS.

Note: In an intercommunications environment, FEPI itself must be run in the application-owning region (AOR), and all transactions that FEPI starts must run locally. This is because FEPI commands cannot be function shipped.

Additionally, ensure that your CICS system has enough storage available to support your FEPI configuration.

Configuring Communications Server SLU P support in CICS for Windows uses the LUA (Logical Unit Application) interface that is provided by Communications Server for Windows. For this interface to be used, Communications Server requires definitions for LUAs and host links to VTAM NCPs.

To configure communications for your FEPI applications, define the following parameters by using the Communications Server configuration program in the 3270/LUA application. v Local Node Characteristics:

Network ID The name of the VTAM network to which this node is connected.

Local node name The name of this workstations local node as defined to VTAM as a physical unit (PU).


Local node ID The node ID for this workstation as defined to VTAM for this PU.

Node type The node type, which must be End Node.

v Devices: Decide whether you are connecting to your network over a local area network (LAN) or Synchronous Data Link Control (SDLC) for LUA API communications.

v Connections: Link station name

Create a new host link definition. Use your desired device type. Partner destination address

A 12-character hexadecimal string that indicates the destination. Adjacent CP name

The partners fully qualified control point name, which should have a type of HOST_XID3.

v LUA API Parameters: LUA LU name

A logical unit application name that can be used by the LUA applications. This name equates to a FEPI node name. Every valid FEPI node name must have an LUA LU name defined for it.

PU name Every LUA must define which local node name it is to use, in order to access a VTAM Network Control Point (NCP). This LUA can then access any back-end systems that this control point knows about in its network.

NAU address The Network Addressable Unit (NAU) is the address of this LUA for your workstations local node. This address (LOCADDR), along with your workstations local node name (PU), map to a host VTAM LU definition in the VTAMLST table.

Availability of network resources For FEPI to communicate with the network by using a node, the Communications Server SNA subsystem must be started, and the link to the host NCP must be available. If FEPI is initialized before both of these resources are available and is instructed to acquire a node, it retries the operation every 30 seconds for up to 30 minutes. Similarly, if a target application is unavailable, FEPI also retries the attempt to initiate a session. After 30 minutes of retrying, the operator must intervene to establish connectivity.

Defining FEPI nodes to VTAM For Communications Server to communicate with the network, some information must be defined to VTAM. For more information about configuring VTAM, see the VTAM Network Implementation Guide and the VTAM Resource Definition Reference. Information about VTAM publications is available on the product Web site.

Each FEPI node is defined to Communications Server as an LUA with a given NAU. The workstations local node name (PU) and a given NAU (or LOCADDR) are mapped by using the VTAMLST table (usually MVS PDS SYS1.VTAMLST) to a given VTAM LU, which is then used for communications with the back-end systems.


For example, the workstation PU WRKS0001 is to be defined with two network-addressable units (NAUs) with LU names FEPI0001 and FEPI0002, using logmode IBM3600. This requires the following definition in VTAM: PULUDEFS VBUILD TYPE=SWNET,MAXNO=50,MAXGRP=1 WRKS0001 PU ADDR=C1, CPNAME=FEPI0001, ... FEPI0001 LU LOCADDR=1,ISTATUS=ACTIVE,DLOGMOD=IBM3600 * LU0 LU FEPI0002 LU LOCADDR=2,ISTATUS=ACTIVE,DLOGMOD=IBM3600 * LU0 LU

Back-end system configuration No special configuration is needed for back-end systems, except that you must provide and manage LUs (simulated terminals) for FEPI use. These terminals are defined to the back-end CICS or IMS system just like real terminals. They can be explicitly defined or autoinstalled as required. They do not need to be defined to VTAM in the back-end system, to which they appear as real terminals on that system. VTAM uses the various network definitions to determine how and where to route data; it can be routed locally, cross-domain, or cross-network. The LU name corresponds to the front-end node name. (Similarly, the VTAM applid of the back-end system corresponds to the applid in the FEPI target definition.)

If your back-end systems use the extended recovery facility (XRF), you must use their generic applids, rather than specific ones, in your FEPI target definitions. See Using FEPI with XRF on page 40.

CICS For CICS back-end systems, acceptable terminal definitions (TYPETERMs) are: v DFHLU2E2 v DFHLU2E3 v DFHLU2E4 v DFHLU2E5 v DFHLU2M2 v DFHLU2M3 v DFHLU2M4 v DFHLU2M5

These definitions match the VTAM mode table entries that are shown in Sample FEPI configuration on page 28. You must create your own TYPETERMs for 3279 model 5 and PS/55 devices, if required, because no such definitions are supplied by CICS. If the back-end system is using CICS/MVS Version 2, you must create all your own TYPETERMs or copy them from the front-end system. For information about defining terminals to CICS, see the TXSeries for Multiplatforms Administration Guide.

IMS For terminals to be used by FEPI, the following settings are required on the TYPE or TERMINAL system definition macros: v NAME must match the NODE name that is specified to, and used by, FEPI. v MODETBL must specify the correct LOGMODE.The following nondefault settings are recommended. (FEPI supports the default settings also.) v Specify OPTIONS=OPTACK for more efficient communications.

Chapter 4. Configuring FEPI 25

v Specify OPTIONS=FORCRESP so that transactions are run in response mode. (If you accept the default instead, you can possibly get nonresponse mode regardless of how the transactions are defined.)

v Specify OPTIONS=NORELRQ to make IMS ignore external requests for the node.

v Specify OPTIONS=BID to indicate that the VTAM BID command should always precede output messages that occur while between brackets.

v Specify OUTBUF=nnn to set a bigger output buffer than the default of 256 bytes.

The following example defines some IMS terminals for use by FEPI. If necessary, customize it for use in your own IMS environment. TYPE UNITYPE=SLUTYPEP,MODETBL=IBM3600, x OPTIONS=(OPTACK,FORCRESP,NORELRQ,BID),OUTBUF=512 TERMINAL NAME=IMSLUP01 NAME IMSLUP01 TERMINAL NAME=IMSLUP02 NAME IMSLUP02 TERMINAL NAME=IMSLUP03 NAME IMSLUP03 TERMINAL NAME=IMSLUP04 NAME IMSLUP04

For further information, see IMS considerations on page 74.

Writing FEPI configuration programs You must write: v A setup program to define your FEPI nodes, targets, property sets, and pools.

You might also need to write: v A monitoring program to handle unexpected events (including setup errors) v Some specialized operator transactions, to simplify the control of FEPI resources v Any common functions that are not provided by individual FEPI applications v One or more global user exit programs

See Chapter 12, Sample programs, on page 79 for details of the samples that are provided.

Writing setup programs You have many conditions to consider when you design setup programs. Therefore, no single way of writing your programs can be recommended. The following samples are supplied on the product CD-ROM: v A COBOL sample setup program with filename DFH0VZXS v A C sample setup program with filename DFH0CZXSThese programs install resources to make FEPI function with the other sample programs. They show you one way of writing setup programs. See Setup on page 83.

Your setup programs must: v Install all node names that are available for FEPI. v Install all targets that FEPI is permitted to access. v Install properties. See Organizing property sets on page 12 for guidance on

which choices to make. When defining the properties of connections in pools, you must set the following options:


Device attributes DEVICE

Data handling FORMAT, MAXFLENGTH, CONTENTION

Session management BEGINSESSION, ENDSESSION, INITIALDATA, STSN

Unexpected events EXCEPTIONQ, UNSOLDATA, UNSOLDATACK

Journaling MSGJRNL, FJOURNALNUM, FJOURNALNAME

v Install pools. v Associate nodes and targets with the pools to define connections.

Note that, by default, FEPI resources are available for use immediately when they are installed or associated with a pool. If you want to override this default for control, performance, or other reasons, you must provide an additional program (or operations procedure) to specify when you want to bring the resources into service.

Many of the FEPI commands that your setup program uses can use lists; using lists helps to improve performance. If some items in a list fail, errors (programming errors and resource problems) are reported to your monitoring program, not to the setup program. If you want to track the errors in the setup program itself, without using the monitoring program, restrict your lists to a single item. Errors are then reported on the command itself.

In addition to a setup program, if needed, you can write a corresponding program to handle the deleting and discarding of resources.

Running setup programs The setup program is typically initiated by a StartupProgramList that is defined in the RD stanza. Using this method, the setup program is run automatically at every CICS startup. The steps are: 1. Write your setup program. 2. Define it to CICS.

Varying the resources installed by the setup program Unless your setup program contains some conditional logic, the same set of FEPI resources are always installed. If you have other requirements, consider the following techniques:

Recording the status of resources If you install all your FEPI resources at CICS startup, then change their accessibility, consider writing a nonterminal transaction that runs frequently and uses the FEPI INQUIRE commands to determine the status of each FEPI resource. Write these to a recoverable temporary storage file. (You can, for example, use an XSZARQ global user exit program to log changes to FEPI resources.) At restart time, your setup program can read the file to determine the required access settings.

Using timed actions You can take advantage of CICS automatic transaction initiation (ATI) at specified times to control FEPI resources. If you want to terminate FEPI access to another


system at a specific time each day, schedule a transaction to run at the required time. When this transaction runs, it can either make the required FEPI resources unavailable for access, or discard them. Because FEPI resources remain available for use by current tasks in this condition, this has no effect on existing FEPI users.

You can use timed initiation in a similar way to make FEPI resources available.

Using event handlers Another way of controlling FEPI resources is to use the begin-session and end-session event handlers. (See Writing other functions on page 34.)

These handlers are invoked when a conversation starts and ends. Although they are primarily designed to handle signon and signoff to the back-end systems, you can take advantage of the fact that all FEPI functions are available to them. So you can use them to control access to back-end systems by either installing or discarding FEPI resources.

For example, suppose you want to ensure that no FEPI application is waiting for a connection to a back-end system. In the handlers, you issue FEPI INQUIRE POOL commands, and look at the WAITCONVNUM option, which returns the number of FEPI applications that are waiting for a connection. If this option exceeds a particular trigger value, issue FEPI commands to increase the number of connections (that is, add nodes, define new pools, and so on).

This technique can be extended to provide tuning of FEPI access to back-end systems.

Sample FEPI configuration A sample configuration is given in Figure 16 on page 29. The following sections provide the target and node lists and the definitions that are used to achieve the sample configuration.


Note: This is not the configuration that the sample programs use; it shows as many aspects of configuration as possible.

Table 2. A sample FEPI configuration Pool name GRPB Property set SLUP Target names IMSB Node names N10 N11 N12 Device type LUP Logmode name IBM3600 Exceptional events queue name IEXEPTP Unsolicited-data transaction name or response IUP Begin-session transaction name ISIP End-session transaction name none STSN transaction name ISTP Initial inbound data No

Sample lists The following target lists and node lists used in the sample configuration, padded to eight bytes per item:

Front End Connections VTAM LUs Back End

CommunicationsServer LUAs

for PU=WRKS01

CICS systemwith FEPI

FEPI definitions

TARGET(IMSA)APPLID(I1)TARGET(IMSB)APPLID(I2)

@LUA0001

@LUA0002

@LUA0003

@LUA0004

LUA=FEPI node name

IYA01

IYA02

IYA03

IYA04

PU + LUA NAU=VTAM LU

IMS System

VTAMAPPLID

I2

IMS System

VTAMAPPLID

I1

Connections in pool GRPA

Connections in pool GRPB

Figure 16. The sample FEPI configuration: a diagrammatic representation


TLIST CICSA IMSA IMSB TLISTA IMSA TLISTB CICSA TLISTC IMSA IMSB TLISTD IMSB

NLIST N10 N11 N12 N20 N30 NLISTA N10 N11 N12 NLISTB N20 NLISTC N30 N10 N11 N12 N20 NLISTD N10 N11 N12 N20

The following is the list of VTAM application names of the back-end CICS and IMS systems with which FEPI applications will communicate. PLIST C1 I1 I2

Sample definitions The following definitions show the various possible ways in which you can define FEPI resources.

Define the back-end subsystems you want FEPI to access This defines the logical names (targets) that FEPI uses to refer to back-end systems (in this case CICSA, IMSA, and IMSB, as given in TLIST), and relates them to their VTAM names (C1, I1, and I2, as given in PLIST). EXEC CICS FEPI INSTALL TARGETLIST(TLIST) TARGETNUM(3) APPLLIST(PLIST)

Define the VTAM minor nodes available to FEPI The names are N10, N11, N12, N20, and N30, as given in NLIST. EXEC CICS FEPI INSTALL NODELIST(NLIST) NODENUM(5)

Define properties This defines the characteristics of the connections.

SLU P connections: EXEC CICS FEPI INSTALL PROPERTYSET(SLUP) LUP /* Device type (SLU P) */ BEGINSESSION(ISIP) /* Begin session handler */ STSN(ISTP) /* STSN transaction */ EXCEPTIONQ(IEXEPTP) /* Exception report TD queue */ UNSOLDATA(IUP) /* Unsolicited-data transaction */ NOTINBOUND /* No "good morning" message */

Define the pools of connections The pools define connections between targets and nodes; they specify which nodes can be used to access which target, and what properties the connection has. EXEC CICS FEPI INSTALL POOL(GRPB) PROPERTYSET(SLUP) TARGETLIST(TLISTD) TARGETNUM(1) NODELIST(NLISTA) NODENUM(3)

Writing monitoring programs You need a monitoring program to handle: v Unexpected events that FEPI reports v Errors in FEPI system programming commands

FEPI reports these events by writing a record to a transient data (TD) queue. You can define pool-specific TD queues for FEPI, where information about events that relate to specific pools is reported. (A common FEPI TD queue, CSZX, also exists,


in which events that do not relate to specific pools are reported.) Note that if a pool-specific event occurs and you have not defined a corresponding queue, information about the event is lost. Also, FEPI TD queues must be defined as nonrecoverable; if a queue is recoverable, FEPI does not write to it and discards any information about unexpected events.

Typically, you can arrange for the monitoring program to be triggered whenever an item is placed into a TD queue. (Define the queue with a trigger level of 1.) A single monitoring program can service several queues by using EXEC CICS ASSIGN QNAME to check which queue triggered it. In accordance with the nature of the event, the monitoring program writes a message, logs the event, or starts a full conversation.

For example, when this method is used, whenever a session is lost, the monitoring program is invoked. The TD queue data provides information about what happened. Your monitoring program can obtain this in the usual way with EXEC CICS READQ TD. The following copy books describe the structure of the data: v DFHSZAPC for C v DFHSZAPO for COBOLYour program can then choose to reestablish the lost session, to reinitialize, and so on. It can also set indicators for the application programs if contact with a target has been lost altogether.

Monitoring programs are written by using the techniques and commands that are discussed in the TXSeries for Multiplatforms Administration Guide. See also the overview of the sample monitoring program in Monitor and unsolicited-data handler on page 84.

Handling unexpected events This section suggests some actions that your monitoring program can take after various types of unexpected event. The type of event is indicated by the EVENTTYPE area in the TD queue record. In most cases, the EVENTVALUE area gives specific details of the failure; the values are the same as the RESP2 values that are listed in the TXSeries for Multiplatforms Administration Reference.

Events in CSZX TD queue records: INSTALLFAIL

A FEPI resource has failed to be installed. This is probably because you are trying to install a duplicate name. This can indicate either a logic error or a possible security violation.

Recommended action: Report possible application logic error, for investigation.

DISCARDFAIL A FEPI resource has not been discarded, probably because you are trying to discard a nonexistent object. This possibly indicates a logic error.

Recommended action: Report a possible application logic error for investigation.

SETFAIL A FEPI resource has rejected a SET request, probably because you are trying to manipulate a resource that does not exist. However, a rejection could occur because of VTAM considerations. So SETFAIL can indicate either a logic error or a network failure.


Recommended action: Schedule a t

Documents

TXSeries for Multiplatforms Front-End Programming Interface for Windows Version 6.2