This article contains information on the installation and configuration of FEPI support within HostBridge. HostBridge includes support for the CICS FEPI interface. HostBridge support for FEPI allows it to access special types of applications. For example:
• CICS applications that cannot execute under a bridge facility (usually because they circumvent the standard CICS terminal control interface).
• Non-CICS applications, such as those that run under IMS.
• Applications provided by an external service provider, and that can be accessed as a VTAM application from within the customers SNA network.
The IBM manual CICS Front End Programming Interface User’s Guide is the primary source of information regarding FEPI installation, operation, and usage. The information below is supplemental or HostBridge-specific. To use FEPI to establish connections to other applications, you must insall and activate FEPI within the CICS region in which HostBridge runs.
For the CICS Systems Programmer
System programmers should read the following sections of the CICS FEPI User's Guide.
• “Getting started with FEPI”: Review and follow the installation steps.
• “Configuring FEPI”: Review the configuration information.
If you plan to run HostBridge in a region in which you already installed FEPI, please contact us. We will review your current configuration to insure that there are no conflicts.
FEPI SIT Parameter
One of the steps described in the CICS FEPI documentation (mentioned above), is specifying FEPI=YES in the SIT. This parameter must be specified in order for FEPI support to be active within a CICS region.
Regarding FEPI Resources
As described in the CICS FEPI User's Guide, there are four types of FEPI resources-pool, property set, target, and node. Figure 4 illustrates the basic relationships between them. Read “Configuring FEPI” in the CICS FEPI User's Guide for more information.
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, such as HostBridge, 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 communication.
Within the CICS environment, FEPI resources are unique in that they are not defined using traditional CICS resource definition techniques (e.g., CSD entries). While the CEMT transaction can be used to manage their state, FEPI resources are defined only when a program executes one of the following commands:
In the CICS FEPI User’s Guide, the section "FEPI Configuration" indicates that a setup program must be written to define your FEPI nodes, targets, property sets, and pools. Such a program is provided as part of HostBridge. It also indicates that you may need to write other types of programs related to FEPI. These programs are also provided with HostBridge.
When FEPI establishes a connection to another VTAM application, the backend system "sees" the connection from HostBridge/FEPI as just another terminal; in fact, the back-end system cannot differentiate between HostBridge/FEPI and a real device. If security is enabled in the back-end system, you must sign on as you ordinarily would from a terminal.
If security for the back-end system is handled by the same External Security Manager (ESM) as the CICS region in which HostBridge is running, then the sign on process can be simplified by using a password substitute - referred to as a "PassTicket". Using a PassTicket to sign on means that the HostBridge requestor (a program or an end user) will not need to re-specify their userid and password to access the back-end system.
When HostBridge establishes a connection to the back-end system via FEPI, HostBridge asks the ESM to generate a PassTicket via the EXEC CICS FEPI REQUEST PASSTICKET command. If the ESM supports PassTicket generation, it will return a PassTicket (a string of 8 characters). This PassTicket is included in the XML document returned by HostBridge. The requesting program can then use this PassTicket on a subsequent sign on request.
Complete information regarding FEPI signon security can be found in the IBM document 'CICS Front End Programming Interface User's Guide'.
Assume the back-end system is another CICS region under the control of the same ESM, and that PassTicket support has been enabled. Further, assume that a requesting program sends the following command string to HostBridge (which causes HostBridge to establish a connection via FEPI):
After HostBridge establishes the connection it will request that a PassTicket be generated and includes it in the XML document returned (the <passticket> element):
Figure 4. Inbound XML document supporting PassTickets
The requesting program would then extract the userid and passticket out of the XML document and send in the following request:
This will cause the CESN command, with the indicated parameters, to be executed in the remote CICS region. As a result, the requestor will now be signed on to the back-end CICS region using the same credentials that were used to sign on to the local CICS region (the region in which HostBridge is running).
For the VTAM Systems Programmer
The primary installation task is to define a group of VTAM application minor nodes that FEPI uses for establishing outbound connections. The number of minor nodes defined determines the maximum number of concurrent connections.
In a subsequent step, the CICS Systems Programmer will use the node names to customize the HostBridge FEPI resource definition program. Thus, you will need to provide the CICS System Programmer with the names of the VTAM minor nodes.
Read the steps related to VTAM configuration outlined in "Configuring FEPI" (CICS FEPI User's Guide). The following information has been excerpted from that section.
Each FEPI node (simulated secondary LU terminal) must have a VTAM application minor node definition. The name of this minor node must be the same as the node name specified on the FEPI INSTALL NODELIST command.
For example, to define FEPI nodes 'FEPI0001' thru 'FEPI0003' the following VTAM application minor node definitions would be required:
The important points to note are:
• If your network uses a naming convention to manage network resources, you can allow a network-independent name to be used by specifying it on the ACBNAME keyword of the VTAM APPL statement. If this is not the case, you can simplify the definition of the VTAM application minor node by omitting the ACBNAME keyword (which means that the margin-name must be the same as the FEPI node name).
• FEPI does not impose any additional restrictions on the naming of nodes, other than that the names should not begin with "DFH"; apart from this, any values acceptable to VTAM are acceptable to FEPI.
• Since the VTAM application minor nodes will be used by FEPI to emulate an SLU type 2 virtual terminal, these "terminals" should have the same characteristics as other terminals in your environment. Thus, if the terminals in your environment are defined to VTAM with a DLOGMODE parameter, then a DLOGMODE parameter should also be specified on the APPL statements. The value of the DLOGMODE parameter should indicate that the virtual terminal is a 3270 model 2 (e.g., DLOGMODE=T3278M2).
CSD Resource Definitions
HostBridge support for FEPI requires the definition of various CICS resources. The figure below lists the CSD resource definitions that must be installed.
Figure 5. CSD resource definitions for HostBridge FEPI support
These statements illustrate adding these resources to a group called HBRFEPI. However, you can also add them to the CSD group that you already use for other HostBridge-related resources.
The table below lists the transactions defined by the CSD definitions in the figure above. (Note the security requirements for each transaction.)
The table below lists the programs defined by CSD definitions
Customizing the FEPI Resource Definition Program
The program HBR0VZXS in HB.V4xxx.HBR.JCL(HBR0VZXS) is the HostBridge FEPI resource definition program, and is provided in source code form. This program installs the resources—property sets, nodes, targets, and pools—that will be used by HostBridge. HBR0VZXS is based upon the IBM sample program DFH0VZXS, and the following program description has been adapted from the CICS FEPI User's Guide. [The source code for the begin session program (HZUC), end session (HZUU), and unexpected event (HZUX) programs are included in the distribution materials (as well as the required copybooks). However, you should not need to modify these programs.]
The definitions of each of these resources are organized so that they can easily be changed. They are kept separate from the processing that does the installation, and there is no hard-coding of values in the CICS commands. There are four main tables, holding details of each resource type. This enables the resources to be changed by repeating sets of definitions which are in an easy-to-understand form. Each table is processed in turn. Nodes and targets are organized into lists for reasons of efficiency. Details of resource installation are written to the CICS log automatically by FEPI.
Before you begin…
• Make sure the SIT specifies FEPI=YES to activate FEPI support in CICS.
• Ask your VTAM systems programmer for the minor node names used to define the VTAM applications.
Step 1: Modify the property sets (optional)
HBR0VZXS defines two property sets. The only difference between them is the "INITIAL" parameter (INBOUND vs. NOTINBOUND). Property set 1 is defined as follows:
Figure 6. Property set definitions
If you change the transaction names, modify the property sets accordingly. If you use the default HostBridge FEPI transaction names (HZUC, HZUU and HZUX), do not modify anything in the default property sets.
If you add or delete a property set, adjust the value of the OCCURS clause in the array definition, which REDEFINES the property set table.
Figure 7. Array definitions for property sets
Step 2: Modify the node names in the node table
Modify the node table in HBR0VZXS to specify the names of the VTAM application minor nodes defined by the VTAM systems programmer.
After you modify the node names, you must adjust the value of the OCCURS clause in the array definition, which REDEFINES the node table (illustrated below).
Figure 8. Array definitions for node names
The OCCURS clause should be set to twice the number of nodes in the table (this accounts for the presence of both the name and password). As provided, HBR0VZXS defines 12 nodes in the node table, so the OCCURS clause specifies 24.
Nodes are defined in HBR0VZXS in a working storage table, as follows:
Figure 9. Node definitions
For each node, two 8-byte fields are defined. The first 8 bytes is for the node name; the second 8 bytes is for the password. If there is no password, which is typically the case, 'LOW-VALUES' is specified. There is no need for these table entries to have field names, as they will be REDEFINED as an array later in the program.
The node names specified in this table must match the names of the application minor nodes defined to VTAM. For example, the above table definitions assume that the following application minor nodes have been defined to VTAM and contained in HB.V4xxx.HBR.JCL(FEPIVTAM):
Figure 10. FEPI definition statements for node definitions
Step 3: Modify targets in the target table
Modify the target table according to your requirements. For example, if you would like the target to be named "TSYS", and the VTAM application id is "TSYSA01", you would specify the following:
Figure 11. Target tables
After you make these changes, you must adjust the value of the OCCURS clause in the array definition, which REDEFINES the node table (illustrated below).
Figure 12. Array definitions for targets
The OCCURS clause should be set to twice the number of targets in the table As provided, HBR0VZXS defines 2 targets in the target table, so the OCCURS clause specifies 4.
Targets are defined in HBR0VZXS in a working storage table, as follows:
Figure 13. Target definitions
Each target table entry defines a single target system. Each entry specifies aname for the target (e.g., HBRTARG1), and the VTAM application id for the application that is to be accessed (e.g., CICS).
Step 4: Modify the pools table
Modify the entries in the Pool table for the property sets, node names, and targets defined in Steps 1-3.
After you customize the pool table entries, you must adjust the value of the OCCURS clause in the array definition, which REDEFINES the pool table (illustrated below).
Figure 14. Array definitions for pools
The value of the OCCURS clause must be equal to the total number of elements defined in all pool table entries. By "elements" we mean each 8 character entry in the pool definition table. For example, in the pool definition below, there are 9 elements: 1 pool name, 1 property set, 6 nodes and 1 target. Since the sample program defines two such pools, the value of the OCCURS clause should be 18.
Pools are defined in HBR0VZXS in a working storage table, as follows:
Figure 15. Pool definitions
A pool definition establishes a relationship between a property set, a group of nodes, and a group of targets. Each pool has a name (e.g., HBRPOOL1). As shown in the example above, the pool definition references the property set, node and target names defined in those tables. Thus, the names must match the names used in the tables.
Step 5: Compile and LINK HBR0VZXS
After you customize HBR0VZXS, you must recompile and link the program using your COBOL compiler. The JCL in HB.V4xxx.HBR.JCL(VZXSCMPL) provides an example.
Figure 16. Sample JCL to compile the HBR0VZXS program
Step 6: Add HBR0VZXS to the PLT (optional)
The FEPI resources used by HostBridge will not be defined and ready for use until HBR0VZXS has executed. Thus, this program should be executed as part of the CICS TS region initialization process. Typically, there are two ways to do this:
1. Define a transaction to run HBR0VZXS, and automatically start this transaction when the region initializes using whatever process/procedure your site adopted.
2. Add HBR0VZXS to the region's PLT (Phase 2); the DFHPLT statement would be:
Verifying FEPI Support
To verify that HostBridge FEPI support installed correctly, please follow the procedure below. Report any problems to HostBridge Support.
Step 1: Test the Sample Application
1. Logon to CICS and run the transaction HZBC. The following screen should be displayed:
2. Enter the value '0001' in the Customer Number field. The following screen should be displayed:
3. Press PF3 to terminate the transaction.
Step 2: Install FEPI Resources
While logged on to CICS, run transaction HZXS to install the FEPI resources. The following screen should display:
After the setup program executes, the message “Setup Completed” displays. The setup program would typically be started by, or as, a PLT program, in which case this message goes to the CICS log. It can, however, be invoked from a terminal and, in this case, the message is sent to the terminal. For clarity, error checking is minimal. In particular, the FEPI INSTALL commands do not check for errors, because FEPI reports any errors that occur to the FEPI transient data queue, and they are then recorded by the monitor program (HBR0VZUX)
Step 3: Test the FEPI Connection
This test procedure uses the HZTD transaction provided with HostBridge. The HZTD transaction establishes a FEPI connection to a specified pool/target, and then allows you to interact with that backend system. Essentially, HZTD allows you to pass-through a CICS region into another backend system.
The HZTD transaction supports the following input parameters:
• pool is the name of the FEPI pool that is to be used to establish the connection. The default is 'HBRPOOL1".
• target is the name of the FEPI target that is to be used to established the connection. If target is specified, it must be the name of a valid target defined within the FEPI pool. If target is not specified, a target will not be specified when the FEPI connection is allocated. As a result, if the pool specifies a single target, then that target will be used. However, if a pool specifies multiple targets, then an error will occur (because a target must be specified in that case).
• tranid is the name of a CICS transaction that is to be executed immediately after the FEPI connection is established. If tranid is not specified, a tranid of ' ' (4 blanks will be specified.
• pfkey is the name of the pf key that will escape out of HZTD and terminate the FEPI session. The default this is PA3. Valid values for pfkey are: CLEAR, PA1, PA2, PA3, PF1, PF2, PF3, PF4, PF5, PF6, PF7, PF8, PF9, PF10, PF11, PF12, PF13, PF14, PF15, PF16, PF17, PF18, PF19, PF20, PF21, PF22, PF23, PF24.
• timeout is the number of seconds that HZTD should wait for a FEPI command to complete. The default is 10.
• trace is either Y or N (the default). If Y is specified, messages will be written to the HBRO TDQ queue reflecting all terminal input/output messages, and FEPI input/output messages.
To run the FEPI test transaction:
1. While logged on to CICS, run transaction HZTD. In this example, we will not specify any input parameters. Thus, a connection will be established using all the default parameters. If you do not know how to use the PA3 key on your PC or terminal, specify a different key using the AID parameter.
2. The following messages will be displayed (the CONVID will be different):
3. Press the ENTER key. Assuming that security is enabled in the target CICS region, and that the default CICS logon (CESN) transaction is automatically started, the following screen should be displayed:
4. Login to CICS as you normally would. If you have connected to the same CICS region in which you are currently signed on and running HZTD, then you will need to use a different userid if your security system does not allow multiple simultaneous login's using the same userid.
5. After you login, clear the screen and start the HZBC transaction. The output displayed on the screen should be the same as if HZBC is executed directly. Thus, the following screen should be displayed:
6. Enter the value '0001' in the Customer Number field. The following screen should be displayed:
7. Press PF3 to terminate the transaction. A blank screen should be displayed.
8. Enter the command CESF LOGOFF. The following screen should be displayed:
9. Press the PA3 key to cause HZTD to terminate the FEPI connection. If the following messages displays, FEPI is operational on your system:
HostBridge includes commands that specifically apply to FEPI transactions. Complete descriptions of these commands may be viewed by clicking on one of the following links: