You must write:
You may also need to write:
See Appendix A. FEPI sample programs for details of the samples that are provided.
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:
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.
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.
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.
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.
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:
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.)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.
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.
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.
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.
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.
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.
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.
Note that this is not the configuration the sample programs use; it illustrates as many aspects of configuration as possible.
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 |
Here are the target lists and node lists used in the sample configuration, padded to eight bytes per item.
The following is the list of VTAM® application names of the back-end CICS and IMS™ systems with which FEPI applications will communicate.
The following definitions illustrate the various possibilities when defining FEPI resources.
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)
The names are N10, N11, N12, N20, and N30, as given in NLIST.
EXEC CICS FEPI INSTALL NODELIST(NLIST) NODENUM(5)
This defines the characteristics of the 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 */
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 */
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 */
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 */
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)
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.
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.
Recommended action: Report possible application logic error, for investigation.
Recommended action: Report possible application logic error, for investigation.
Recommended action: Schedule a transaction to repeat the operation (if not a logic error).
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.
Recommended action: Suggest that the operator:
Recommended action: After FEPI stops retrying, suggest the operator:
Recommended action: Report possible application logic error, for investigation.
Recommended action: Report possible application logic error, for investigation.
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.
The three most likely scenarios are described in the following sections.
FEPI unconditionally rejects the bind request.
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.
The necessary resource definitions must be managed dynamically.
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.
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.
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.
The CLSDST(PASS) occurred as a result of trying to acquire a connection. The monitor program should:
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.
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.
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.
Two CICS global user exits are provided:
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 ]]