FEPI configuration

You must write:

You may also need to write:

See Appendix A. FEPI sample programs for details of the samples that are provided.

Writing configuration programs

FEPI programs are CICS® applications, and so all aspects of CICS programming apply. For guidance about writing CICS application programs, see the CICS Application Programming Guide. For programming information, (including command formats, argument values, details on the translation of programs, and language considerations), see the CICS Application Programming Reference. Particularly relevant are the chapters in the the CICS Application Programming Guide about designing efficient applications and dealing with exception conditions.

The FEPI system programming commands are an extension of the EXEC CICS commands. They have similar names and similar functions. The FEPI commands also have similar keywords, but they are distinguished by having "FEPI" as a prefix. For system programming, the commands are:

Definition:
EXEC CICS FEPI INSTALL
Define communication resources
EXEC CICS FEPI ADD
Add resources to a pool
EXEC CICS FEPI DELETE
Remove targets or nodes from a pool
EXEC CICS FEPI DISCARD
Remove communication resources completely from FEPI.
Operations:
EXEC CICS FEPI INQUIRE
Query FEPI status and resources
EXEC CICS FEPI SET
Control FEPI resources.

Note that, when translating your programs, you must specify the FEPI option, which instructs the translator to process FEPI commands, but you do not need the SP option.

Your FEPI configuration programs can be AMODE(24) or AMODE(31)--that is, they can issue FEPI commands in either 24- or 31-bit addressing mode, and reside above or below the 16MB line.

Exception conditions

As with all CICS commands, FEPI commands may produce exception conditions that you can check using the RESP option, or capture using HANDLE CONDITION. Most FEPI command errors return INVREQ. The particular error in each case is uniquely identified by the RESP2 value. All the FEPI exception conditions and RESP2 values are listed in FEPI system programming reference. There are copy books that contain declarations for the RESP2 values:

For the system programming commands, errors are reported as unexpected events to the CSZX or other transient data queue, and to the FEPI message log CSZL, as well as by exception conditions on the command.

If there is an error, the command does nothing, and output values are not changed. Some commands operate on a list of resources; an error in one resource does not prevent the command from operating on the other resources in the list.

You can use EDF and CECI to debug FEPI programs. Because FEPI commands can be quite long, you will probably find the NAME field of CECI useful.

All resource names used by FEPI are a fixed length of 8 characters; they must be padded with blanks if necessary. For commands that use lists, make sure that the list field is a multiple of 8 characters long and that the number option is set correctly; neither the translator nor CECI checks these and unpredictable results could occur if they are wrong.

Writing setup programs

There are many considerations in designing setup programs, and so there is no single recommended way of writing them. On the distribution tape, there is:

These programs install resources to make FEPI function with the other sample programs. They show you one way of writing setup programs. See Setup.

Your setup programs must:

Note that, by default, FEPI resources are available for use as soon as they are installed or associated with a pool. For control, performance, or other reasons, you might want to override this; if so, you must provide a further program (or operations procedure) to bring the resources into service when you require them.

Many of the FEPI commands used by your setup program can use lists; using lists helps to improve performance. If some items in a list fail, errors (both 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, you may need a corresponding program to deal with deleting and discarding resources.

Running setup programs

The setup program is typically initiated by a program list table (PLT) program. Using this method, the setup program is run automatically at every CICS startup, including an XRF takeover. Follow this procedure:

  1. Write your setup program.
  2. Define it to CICS, using RDO, and associate it with a transaction.
    Note:
    You can define your setup program statically, or allow it to be installed automatically (autoinstalled) when it is invoked. For details of the CICS autoinstall facility for programs, see the CICS Resource Definition Guide.
  3. Write a PLT program containing the command
    EXEC CICS START TRANSID(tranid) INTERVAL(1)
    where tranid is the ID of your setup transaction. (For programming information about writing PLT programs, see the CICS Customization Guide.)
  4. Define your PLT program to CICS, and include it in the second part of the program list table post initialization (PLTPI) list. (For information about coding entries in the PLTPI list, see the CICS Resource Definition Guide.)

There may be a good reason for you to decide not to use the PLT to start the setup transaction. For example, you may want to have several, time-sensitive, setup programs, each having a corresponding discard program. If you decide not to use the PLT, you must arrange to start the setup transactions manually.

You should restrict access to the setup programs, because they are of a sensitive nature.

Varying the resources installed by the setup program

Unless your setup program contains some conditional logic, you always get the same set of FEPI resources installed. This may be exactly what you require, but if not, here are a few techniques that might prove useful.

Checking startup type

Your setup program can determine how the CICS system started by issuing an EXEC CICS INQUIRE SYSTEM STARTUP command. It could use this to install different sets of FEPI resources for warm and cold starts.

Recording the status of resources

If you install all your FEPI resources at CICS startup, and then alter their accessibility, consider writing a non-terminal 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 could, 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 could 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 circumstance, this has no effect on existing FEPI users.

You could 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 Other functions.)

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, issue FEPI INQUIRE POOL commands, and look at the WAITCONVNUM option, which returns the number of FEPI applications waiting for a connection. If this option exceeds a certain 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 Table 4. Next, the target lists and node lists used in the sample are given. Then there are the definitions used to achieve the sample configuration. Figure 2 is a diagrammatic representation of the sample configuration.

Figure 2. The sample FEPI configuration--a diagrammatic representation
 The picture is a diagrammatic representation of the sample configuration. It shows a front-end CICS system that uses FEPI, and three back-end systems (one CICS and two IMS). The back-end systems have VTAM APPLIDs of C1, I1, and I2. The front-end CICS has defined these APPLIDs as FEPI targets. The picture shows the FEPI connections between the front-end CICS and the back-end systems, together with the pools and nodes used by the sample configuration.
 

Note that this is not the configuration the sample programs use; it illustrates as many aspects of configuration as possible.

Table 4. A sample FEPI configuration
Pool name GRPB GRPC GRPD GRPE GRPF
Property set SLUP SLU2M3I SLU2M3I SLU2M2I SLU2M2C
Target names IMSB IMSA IMSB IMSA IMSA IMSB CICSA
Node names N10 N11 N12 N30 N10 N11 N12 N20 N10 N11 N12 N20
Device type LUP T3278M3 T3278M3 T3278M2 T3278M2
Logmode name IBM3600 D4A32783 D4A32783 D4A32782 D4A32782
Exceptional events queue name IEXEPTP IEXEPT2 IEXEPT2 IEXEPT2 CEXEPT2
Unsolicited-data transaction name or response IUP IU2 IU2 IU2 Negative
Begin-session transaction name ISIP ISI2 ISI2 ISI2 CSI2
End-session transaction name none IXI2 IXI2 IXI2 CXI2
STSN transaction name ISTP n/a n/a n/a n/a
Initial inbound data No Yes Yes Yes Yes

Sample lists

Here are the target lists and node lists used in the sample configuration, padded to eight bytes per item.

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 '
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 illustrate the various possibilities when defining 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 */
SLU2 24 x 80 connections to IMS
EXEC CICS FEPI INSTALL PROPERTYSET(SLU2M2I)
     T3278M2                  /* Device type (3278 model 2, 24 x 80) */
     BEGINSESSION(ISI2)       /* Begin session handler */
     EXCEPTIONQ(IEXEPT2)      /* Exception report TD queue */
     UNSOLDATA(IU2)           /* Unsolicited-data transaction */
     INBOUND                  /* Initial data */
     ENDSESSION(IXI2)         /* End session handler */
SLU2 32 x 80 connections to IMS

EXEC CICS FEPI INSTALL PROPERTYSET(SLU2M3I)
     T3278M3                  /* Device type (3278 model 3, 32 x 80) */
     BEGINSESSION(ISI2)       /* Begin session handler */
     EXCEPTIONQ(IEXEPT2)      /* Exception report TD queue */
     UNSOLDATA(IU2)           /* Unsolicited-data transaction */
     INBOUND                  /* Initial data */
     ENDSESSION(IXI2)         /* End session handler */
SLU2 24 x 80 connections to CICS

EXEC CICS FEPI INSTALL PROPERTYSET(SLU2M2C)
     T3278M2                  /* Device type (3278 model 2, 24 x 80) */
     BEGINSESSION(CSI2)       /* Begin session handler */
     EXCEPTIONQ(CEXEPT2)      /* Exception report TD queue */
     NEGATIVE                 /* Response to unsolicited data */
     INBOUND                  /* "Good morning" message */
     ENDSESSION(CXI2)         /* End session handler */
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)
EXEC CICS FEPI INSTALL POOL(GRPC) PROPERTYSET(SLU2M3I)
     TARGETLIST(TLISTC) TARGETNUM(2)
     NODELIST(NLISTC) NODENUM(1)
EXEC CICS FEPI INSTALL POOL(GRPD) PROPERTYSET(SLU2M3I)
     TARGETLIST(TLISTA) TARGETNUM(1)
     NODELIST(NLISTA) NODENUM(3)
EXEC CICS FEPI INSTALL POOL(GRPE) PROPERTYSET(SLU2M2I)
     TARGETLIST(TLISTC) TARGETNUM(2)
     NODELIST(NLISTB) NODENUM(1)
EXEC CICS FEPI INSTALL POOL(GRPF) PROPERTYSET(SLU2M2C)
     TARGETLIST(TLISTB) TARGETNUM(1)
     NODELIST(NLISTD) NODENUM(4)

Writing monitoring programs

You need a monitoring program to handle:

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. (There is also a common FEPI TD queue, CSZX, where 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 would arrange for the monitoring program to be triggered whenever an item is placed in 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. According to the nature of the event, the monitoring program might simply write a message, log the event, or embark on a full conversation.

For example, using this method, 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:

Your program may then choose to reestablish the lost session, to reinitialize, and so on. It may also set indicators for the application programs if contact with a target has been lost altogether.

Monitoring programs are written using the techniques and commands discussed in FEPI application programming. See also the overview of the sample monitoring program in Monitor and unsolicited data-handler.

Handling unexpected events

This section suggests some actions your monitoring program could 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 listed in RESP2 values.

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 may 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. This is probably because you are trying to discard a nonexistent object. This may indicate a logic error.

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

SETFAIL
A FEPI resource has rejected a SET request. This is probably because you are trying to manipulate a resource that does not exist. However, there is also the possibility of rejection due to VTAM considerations. So SETFAIL may indicate either a logic error or a network failure.

Recommended action:  Schedule a transaction to repeat the operation (if not a logic error).

ACQFAIL
A FEPI resource has failed to be acquired. This is probably because of a network failure, and so FEPI automatically retries the acquire request several times at intervals; the count in EVENTDATA shows whether there will be any more retries. However, there is also the possibility of an error in either the VTAM definition or the back-end system definition of the object.

Recommended action:   After FEPI stops retrying, suggest investigating the condition of the resource from a VTAM viewpoint. The VTAM sense code describing the problem is in EVENTDATA. See the appropriate VTAM manual for more information. For nodes, this is the VTAM Programming manual; for connections, VTAM Messages and Codes. Further information is in the SNA Formats manual.

SESSION
An unsolicited bind was received, probably because of a CLSDST(PASS). See Handling CLSDST(PASS).

Events in pool-specific TD queue records

SESSIONLOST
An active connection has failed. This is probably due to the back-end system failing. However, this error is also generated if an operator cancels an active connection.

Recommended action:  Suggest that the operator:

SESSIONFAIL
A connection has failed to start. This is probably due to a setup inconsistency or to a failure of the back-end system, and so FEPI automatically retries the acquire request several times at intervals; the count in EVENTDATA shows whether there will be any more retries. However, this failure is also generated if an operator has canceled the connection.

Recommended action:   After FEPI stops retrying, suggest the operator:

ADDFAIL
An attempt to add a target or node to a pool has failed. The probable cause of this error is an attempt to add a resource that is already in the pool. This indicates a possible logic error.

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

DELETEFAIL
An attempt to delete a target or node from a pool has failed. This is probably caused by an attempt to delete a resource that is not in the pool, indicating a possible logic error.

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

Handling CLSDST(PASS)

A back-end system can end a network session with a VTAM CLSDST(PASS) request. This indicates that the back-end will reestablish a session with the front-end using a different PLU name (a third-party PLU). The front-end system detects reestablishment of the session by receiving an unsolicited bind request; so when the back-end system ends a session, it is important for it to indicate that an unsolicited bind is to be expected.

Note:
To determine whether a lost session was caused by a CLSDST(PASS) request, a FEPI application can issue a FEPI INQUIRE CONNECTION command. If the value of LASTACQCODE is X'32020000', the back-end system issued a CLSDST(PASS) to unbind the session.

The three most likely scenarios are described in the following sections.

Unsolicited bind not expected

FEPI unconditionally rejects the bind request.

Third-party PLU name known and unsolicited bind expected

The prospective PLU names must be defined to FEPI as targets. You might need to restrict access to the pools that include these targets to make sure the connection is not already in use when the CLSDST(PASS) takes place. The simplest way to configure this is to define a pool containing the node and all the targets it can be placed in session with. Install all connections except the initial one with an ACQSTATUS of RELEASED so the back-end system can successfully acquire the session. No other special processing is required and no TD queue record is written in this case.

Third-party PLU name not known and unsolicited bind expected

The necessary resource definitions must be managed dynamically.

Note:
Managing the resource definitions dynamically (described under Conversation in progress) is the only method that allows the conversation to persist across the CLSDST(PASS).

When FEPI receives the unsolicited bind, it writes a record to the CSZX TD queue, with an EVENTTYPE of SESSION, and with the third-party PLU name in the TARGET area. At this point, the bind has not been accepted or rejected. A VTAM display for either the back-end or the front-end system would show the connection to be in a PSESST/B state. You are responsible for managing these TD queue records and making the necessary FEPI configuration updates so that processing can continue. If no action is taken, the session remains in this state until a VTAM VARY NET,TERM command is issued to terminate the session request.

There are two cases, according to whether or not there is a conversation in progress on the connection when the CLSDST(PASS) occurs. (This can be determined from the STATE option of the FEPI INQUIRE CONNECTION command.) In both cases, you need to determine which pool has the connection that the CLSDST(PASS) applies to, because the TD queue record does not report either the pool or the old target name. If the node is used in only one pool, the old target name can be found easily by browsing connections using FEPI INQUIRE CONNECTION; if not, use some other technique, such as the USERDATA option of the FEPI SET commands.

Conversation in progress

Nodes for which this kind of processing is required should be defined in pools containing only the node and the initial target, because of the nature of the processing involved.

The monitor program should:

  1. Install a new pool with the same properties as the current one.
  2. Install a new target whose PLU name is the third-party PLU name given in the TARGET area of the TD queue record.
  3. Add the target to the new pool. This should be the only target in that pool.
  4. Delete the node identified in the TD queue record from the pool in which it currently exists. If necessary, to ensure continuity, the monitor program can add another node to the pool before deleting the old node.
  5. Add the node to the newly created pool. The new connection is now established.

When the session ends, the connection reverts to a RELEASED state. If necessary, use an end-session handler to perform any necessary cleanup, such as reversing the process described above.

The front-end application must also anticipate CLSDST(PASS) processing. See Lost session for more details.

Conversation not in progress

The CLSDST(PASS) occurred as a result of trying to acquire a connection. The monitor program should:

  1. Install a new target whose PLU name is the third-party PLU name given in the TARGET area of the TD queue record.
  2. Add the target to the pool, specifying a desired connection acquire status of ACQUIRED. The new connection is now established.

If necessary, use an end-session handler to cleanup the dynamically defined targets. These connections always become RELEASED when the session ends and can be left for reuse, if required.

Writing operator transactions

You might find it useful to write some specialized operator transactions of your own to control FEPI resources. For more information, see Controlling FEPI resources.

Other functions

The other functions you might need to write for FEPI itself are the begin-session, end-session, and unsolicited-data handlers. These are extensions of the FEPI application programs, and are described in FEPI application programming. If you write them as common functions, you need to know what the application programs do. Alternatively, the application programmer may write them.

Global user exit programs

Two CICS global user exits are provided:

XSZBRQ
Invoked before a FEPI command is executed
XSZARQ
Invoked after a FEPI command is executed.

XSZBRQ is passed the parameters input to the command, and can be used to monitor commands, to bypass commands that violate installation conventions, or to change the parameters of a command, subject to the rules applying to global user exits. XSZARQ is passed the parameters output from the command.

For details of the FEPI global user exits, see FEPI global user exits. For programming information about writing and using global user exit programs, see the CICS Customization Guide.

[[ Contents Previous Page | Next Page Index ]]