This program installs the resources--property sets, nodes, targets, and pools--that are used by the FEPI sample programs.
Module names: DFH0VZXS, DFH0AZXS, DFH0CZXS
Transaction name: CZXS
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. If desired, the program could be changed to obtain the resource definitions from a file.
The resources defined are:
Pool Property set Nodes Targets
POOL1 PROPSET1 NODE1 NODE2 NODE3 TARGET1
NODE4 NODE5
POOL2 PROPSET2 NODE6 NODE7 NODE8 TARGET1
NODE9 NODE10
POOL3 PROPSET3 NODE1 NODE2 NODE3 TARGET2
NODE4 NODE5
You must customize these definitions to match the requirements of your system. If you do, you may also need to change the definitions in the sample customization constants copy book DFH0BZCx. You do not need to change any other samples--you need simply recompile them.
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.
On completion, a message is sent. The setup program would typically be started by a PLT program, in which case the 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 errors at all, because FEPI reports any errors that occur to the FEPI transient data queue, and they are then recorded by the sample monitor program.
For each property set in table
FEPI INSTALL PROPERTYSET
For each node in table
Add node to list
FEPI INSTALL NODELIST
For each target in table
Add target to list
FEPI INSTALL TARGETLIST
For each pool in table
Start new lists of nodes and targets
For each entry within pool definition
If node, add details to node list
If target, add details to target list
FEPI INSTALL POOL with NODELIST and TARGETLIST
Send completion message
RETURN
This program monitors unexpected events and handles unsolicited data for the FEPI sample programs.
Module name: DFH0VZUX
Transaction name: CZUX
TS queue name: MONITOR
This transaction handles:
Because the event descriptions provided by FEPI and the processing required is basically the same for both cases, this common program is used.
ASSIGN STARTCODE is used to determine how the transaction was started, and ASSIGN QNAME to determine what TD queue triggered it. Details of the event are in the start data or the TD queue record as the case may be.
For illustrative purposes, all events are handled similarly by simply reporting their details to a TS queue named MONITOR, which can be browsed using CEBR. In practice, for any of the events you can do whatever extra or different processing you require, or (except for unsolicited data) you can ignore the event.
For unsolicited data, the conversation started by FEPI must be accessed so that FEPI knows that the data is being handled. The data itself should be received, or else FEPI ends and restarts the session. For illustration purposes, this program simply discards the data; in practice, you will probably want to process the data in some way.
However, if you did simply want to discard such data, you should specify no unsolicited-data handling and use the UNSOLDATACK property to tell FEPI what action to take, as is done for SLU P mode by these samples.
The general format of the TS queue records is:
date time CZUX description
Event type..ACQFAIL Pool........POOLNAME
Target......TGTNAME Node........NODENAME
Device......T3278M2 Event data..X'00000000'
Format......0 Event value.176
The actual details for each event vary. Events with similar details are grouped together for processing. The groups are:
The groups also determine any additional processing needed. Only unsolicited data needs any processing.
If any errors occur, they are reported to the TS queue.
Main procedure:
Determine how transaction was started using ASSIGN
If started with data by FEPI
RETRIEVE start data
If triggered by TD queue
READ the queue record
Otherwise
Report start code
RETURN
TD-LOOP:
Locate event type
Locate device type
Build description of event: event type, device type,
format, event value, date/time, transaction
Call UNKNOWN-EVENT, UNSOLDATA, STANDARD-EVENT, or
SESSION-LOST according to event group
If triggered by TD queue
READ the next queue record
If one exists, loop to TD-LOOP
RETURN
UNKNOWN-EVENT routine:
Write event details to TS queue: description and
event value
UNSOLDATA routine:
Write event details to TS queue: description, event
type, pool, target, and node
Access conversation using FEPI ALLOCATE with PASSCONVID
FEPI RECEIVE unsolicited data
Free conversation
Handle data as required
STANDARD-EVENT routine:
Write event details to TS queue: description, event
type, pool, target, node, device, event data,
format, and event value
SESSION-LOST routine:
Write event details to TS queue: description, event
type, pool, target, node, device, and format
This program prepares sessions for use by the FEPI sample application programs.
Module name: DFH0VZUC
Transaction name: CZUC
TS queue name: SESSION
This transaction is started by FEPI when it begins a new session.
The conversation started by FEPI must be accessed so that FEPI knows that the event is being handled. The processing required depends on the data mode and type that the session uses (this is obtained from the start data), and whether the back-end system is IMS™ or CICS.
For SLU P mode (necessarily IMS), processing depends entirely on local requirements, and is typically used for handling security applications. For illustration purposes, this program simply gets and discards the initial data. Note that the setup for these samples does not specify a begin-session transaction for SLU P mode.
For SLU2 mode with CICS using formatted data, there is a CICS "good morning" message waiting. The message is received, and the back-end screen is cleared and left ready for a transaction ID to be entered.
For SLU2 mode with CICS using data stream, there may be a "read partition" request waiting which requires a reply--for example, if your pool has device T3279Mx or TPS55Mx specified, or if the logon mode table being used has "extended data stream" specified). Then there is a CICS "good morning" message to be received. A reply is sent to any "read partition" query request, the "good morning" message is received, and the back-end screen is cleared and left ready for a transaction ID to be entered.
For SLU2 mode with IMS, no processing is illustrated.
After the processing, the conversation is freed with the HOLD option, which leaves it ready for use by applications. A report is written to a TS queue named SESSION, which can be browsed using CEBR. The format of the TS queue records is:
date time CZUC Begin session completed
RESP........0 RESP2.......0
Target......TGTNAME Node........NODENAME
Pool........POOLNAME
If any errors occur, a report is written to the TS queue, and the conversation is freed with the RELEASE option, so that the session is ended.
Main procedure:
RETRIEVE start data
Access conversation using FEPI ALLOCATE with PASSCONVID
Call PROCESS-LUP, PROCESS-FORMATTED, or
PROCESS-DATASTREAM according to data mode and type
Free conversation, keeping session
Write event details to TS queue
RETURN
PROCESS-LUP routine:
FEPI RECEIVE initial data
Handle data as required
PROCESS-FORMATTED routine:
FEPI RECEIVE initial data
Clear back-end screen and make ready for transaction ID
to be entered, using FEPI CONVERSE
PROCESS-DATASTREAM routine:
FEPI RECEIVE
If 'read partition' query
FEPI CONVERSE query reply and get acknowledgement
FEPI RECEIVE initial data
Clear back-end screen and make ready for transaction ID
to be entered, using FEPI CONVERSE
This sample program demonstrates using FEPI to obtain information from a back-end transaction using the key stroke data format.
Module names: DFH0VZTK, DFH0PZTK, DFH0CZTK
Transaction name: CZTK
Map names: DFH0MZ1, DFH0MZ6, DFH0MZ7
CZTK Customer Name and Address Inquiry Please type a customer number in the range 1 through 9999, then Enter. Customer Number . . . . . Name . . . . . : Address. . . . : F3=EXIT to CICS
On the first invocation of the transaction, a map is sent to the front-end terminal.
When there is input from the front-end terminal, CICS invokes the transaction again. The customer number from the input is built into a key stroke sequence which runs a transaction at the back-end. The key strokes are sent and the results received using a FEPI ALLOCATE-CONVERSE-FREE command sequence. Information is extracted from the results and sent to the front-end terminal. Further input is then awaited.
When PF3 or CLEAR is received from the front-end terminal, the transaction ends. If there is an error, the front-end map is reset. These situations are detected using HANDLE CONDITION.
If the back-end sends a CICS message, it is sent on to the front-end terminal, and the transaction ends.
For clarity, error checking is minimal except for the FEPI commands. Note that the key stroke sequence used involves several attention keys, so that if the intermediate responses are not what is expected, the effects are unpredictable. According to your requirements, it may be advisable to send each attention sequence individually and to check each time that the results are as expected.
MAIN procedure:
Test COMMAREA
If transaction not previously invoked
Call SEND-NEW-MAP
Set up exception condition handling:
Map error - SEND-NEW-MAP
CLEAR/PF3 - END-PROG
RECEIVE MAP from front-end terminal
Build key stroke sequence to:
clear back-end screen
type transaction ID
ENTER
type the customer number
ENTER
FEPI ALLOCATE conversation with back-end
FEPI CONVERSE to send key strokes to back-end and get
the resulting screen image
FEPI FREE conversation with back-end
If CICS message received from back-end
SEND message to front-end terminal
RETURN
Get customer information from back-end screen image
Build data for front-end terminal map
SEND map data to front-end terminal
RETURN TRANSID(CZTK) with COMMAREA
SEND-NEW-MAP routine:
SEND new map to front-end terminal
RETURN TRANSID(CZTK) with COMMAREA
END-PROG routine:
Clear front-end terminal
RETURN
This sample program demonstrates using FEPI to send formatted data to a back-end transaction, and requesting a transaction to be started when the reply to the data arrives.
Module name: DFH0VZTS
Transaction name: CZTS
Map name: DFH0MZ2
CZTS Customer Name and Balance Inquiry Please type a customer number in the range 1 through 9999, then Enter. Customer number . . . . . Name . . . . . : Balance. . . . : F3=EXIT to CICS
This program is the SEND part of a SEND-RECEIVE pair of programs, the RECEIVE part being DFH0VZTR.
On the first invocation of this send transaction, a map is sent to the front-end terminal.
When there is input from the front-end terminal, CICS invokes this send transaction again. The customer number is extracted from the input. Using FEPI ALLOCATE a conversation is started with the back-end system. Then FEPI SEND with screen image data is used to start a back-end transaction. FEPI START is issued to specify that the receive transaction is to be started when the back-end system replies.
In due course, the receive transaction is started and XCTLs to this send transaction. The customer number can now be sent to the back-end using FEPI SEND with screen image data. FEPI START is again issued.
The receive transaction gets the results from the back-end transaction and sends them on to the front-end terminal.
When there is more input from the front-end terminal, CICS invokes this transaction again. FEPI ALLOCATE with PASSCONVID is issued to gain ownership of the conversation and the customer number is sent to the back-end as before. The cycle continues until PF3 or CLEAR is received. These are passed on to the receive transaction (using the FEPI START user data) and to the back-end transaction to indicate that it is to end.
MAIN procedure:
Test COMMAREA
If transaction not previously invoked
Call SEND-MAP
If first customer number to process
Call CONTINUE-CONVERSATION
Set up exception condition handling:
Map error - SEND-MAP
PF3/CLEAR - CONTINUE-CONVERSATION
RECEIVE MAP from front-end terminal
If conversation not started
Call INITIATE-CONVERSATION
Else
Call CONTINUE-CONVERSATION
SEND-MAP routine:
SEND new map to front-end terminal
RETURN TRANSID(CZTS) with COMMAREA
INITIATE-CONVERSATION routine:
FEPI ALLOCATE conversation with back-end
Build screen image to invoke back-end transaction
FEPI SEND screen image to back-end
FEPI START the receive transaction
RETURN
CONTINUE-CONVERSATION routine:
Unless first customer number
Reaccess conversation with FEPI ALLOCATE PASSCONVID
Build screen image to send customer number
FEPI SEND screen image to back-end
FEPI START the receive transaction
RETURN
This sample program demonstrates using FEPI to get formatted data from a back-end transaction.
Module name: DFH0VZTR
Transaction name: CZTR
Map name: DFH0MZ2
See Figure 12.
This program is the RECEIVE part of a SEND-RECEIVE pair of programs, the SEND part being DFH0VZTS.
This transaction is started by CICS either when data is received from the back-end transaction or if no data is received in the time set in the send transaction, as is determined from the start data obtained with RETRIEVE. The user data in the start data indicates whether the conversation is starting, continuing, or finishing.
A FEPI RECEIVE obtains the screen image from the back-end transaction and FEPI EXTRACT FIELD is used to obtain specific fields.
If the conversation is starting, control is passed to the send transaction using XCTL to allow an inquiry to be sent to the back-end transaction.
If the conversation is continuing, the results from the back-end are sent on to the front-end terminal. Access to the conversation is relinquished, and control is returned to CICS specifying that the send transaction is to be invoked when there is next user input.
If the conversation has finished, a message to that effect is sent to the front-end terminal. The conversation is freed and the transaction ends.
MAIN procedure:
RETRIEVE start data
Reaccess conversation with FEPI ALLOCATE PASSCONVID
If time out
Call REPORT-PROBLEM
FEPI RECEIVE back-end screen image
If conversation ending (PF3 or CLEAR indicated)
Call REPORT-PROBLEM
If back-end problem
(CICS message or back-end transaction message)
Call REPORT-PROBLEM
If conversation starting (user data has customer number)
XCTL to program DFH0VZTS
If conversation continuing
Get interesting fields from back-end data using
FEPI EXTRACT FIELD
Build and send map to front-end terminal
Release conversation using FEPI FREE PASS
RETURN TRANSID(CZTS) with COMMAREA
REPORT-PROBLEM routine:
SEND message to front-end terminal
FEPI FREE conversation
RETURN
This sample program demonstrates using FEPI to pass-through 3270 data stream between a back-end application and a front-end terminal.
Module names: DFH0VZTD, DFH0AZTD
Transaction name: CZTD
On the first invocation of the transaction, a request is sent to the back-end system to start a transaction there. The response is sent on to the front-end terminal.
When there is input from the front-end terminal, CICS reinvokes the transaction. This input is sent on to the back-end system, using the FEPI CONVERSE command, and the resulting response is returned to the front-end terminal.
If there is an error, or the back-end system sends a CICS message, or PF3 is received from the front-end terminal, the transaction ends.
Test COMMAREA
If transaction not previously invoked
Build data stream request to start back-end transaction
FEPI ALLOCATE conversation with back-end system
FEPI CONVERSE data stream to and from back-end system
SEND returned data stream to the front-end terminal
Else
RECEIVE data stream from the front-end terminal
Prepare data stream to send on to back-end system
Reaccess conversation with FEPI ALLOCATE PASSCONVID
FEPI CONVERSE data stream to and from back-end system
SEND data stream to the front-end terminal
If error during processing
SEND explanatory message
If continuing
Release conversation using FEPI FREE PASS
RETURN TRANSID(CZTD) with COMMAREA
Else (error, CICS message, or PF3)
FEPI FREE conversation
RETURN
This program cleans up sessions after use by FEPI sample application programs.
Module name: DFH0VZUU
Transaction name: CZUU
TS queue name: SESSION
This transaction is started by FEPI when an application ends a conversation or when a session is released.
The conversation passed by FEPI must be accessed so that FEPI knows that the event is being handled. The processing required depends entirely on local requirements. For illustration purposes, this program simply keeps the session for use by another conversation or lets it end, depending on the event type.
The CONVID picked up from
the START data and passed on the FEPI ALLOCATE PASSCONVID is not the same
as the CONVID for the conversation that has been freed. Nevertheless, the
end-session handler can use it to access the same FEPI terminal.
For end of conversation (EVENTTYPE=FREE in start data), processing could typically involve setting the session back to a known state (such as a clear back-end screen ready to accept a new transaction name), or handling security, or overriding the type of FREE used. Such processing would depend on the data mode and type that the session uses (which is obtained from the start data), whether the back-end system is CICS or IMS, and the type of FREE used (also obtained from the start data).
For end of session (EVENTTYPE=FREE and EVENTVALUE=RELEASE in start data), processing could typically involve handling security.
For both cases, there could be an indication (in EVENTVALUE in the start data) that CICS is shutting down, which might require alternative special processing. This transaction would have to be in the XLT to allow it to be started during shutdown.
After the processing, a report is written to a TS queue named SESSION, which can be browsed using CEBR. The format of the TS queue records is:
date time CZUU End-session handling completed
RESP........0 RESP2.......0
Target......TGTNAME Node........NODENAME
Pool........POOLNAME
Main procedure:
RETRIEVE start data
Access conversation using FEPI ALLOCATE with PASSCONVID
Call PROCESS-RELEASE or PROCESS-FREE as appropriate
Write event details to TS queue
RETURN
PROCESS-RELEASE routine:
Handle as required
Free conversation, ending session
PROCESS-FREE routine:
Handle as required
Free conversation, keeping session
This sample program demonstrates using FEPI to obtain information from a back-end IMS system, using SLU P mode and the FEPI CONVERSE command with the POOL option.
Module names: DFH0VZPS, DFH0AZPS
Transaction name: CZPS
Map names: DFH0MZ4, DFH0MZ8
CZPS SLU P Sample Program. IMS SLU P conversational sample program This transaction will process a FEPI CONVERSE command to obtain time and date from a back-end IMS system. DATE : 02/04/92 TIME : 10:57:10 STATE : Not started F3=EXIT to CICS ENTER=obtain time and date stamp from IMS
On the first invocation of the program, a map is sent to the front-end terminal.
When there is input from the front-end terminal, CICS reinvokes the program. A simple inquiry is made to the back-end system--for illustration purposes, it asks the time--and the answer is displayed on the front-end terminal. Because the inquiry requires only a one-out one-in exchange with the back-end system, a temporary conversation can be used, so the FEPI CONVERSE command with the POOL option is used.
When PF3 or CLEAR is received from the front-end terminal, the transaction ends. If there is an error, the front-end map is reset. These situations are detected using HANDLE CONDITION.
If the back-end system sends an IMS message, it is sent on to the front-end terminal and the transaction ends.
For clarity, error checking is minimal except for the FEPI commands.
MAIN procedure:
Test COMMAREA
If transaction not previously invoked
Call SEND-NEW-MAP
Set up exception condition handling:
Map error - SEND-NEW-MAP
CLEAR/PF3 - END-PROG
RECEIVE MAP from front-end terminal
Build SLU P data stream to request time from back-end IMS
system
FEPI CONVERSE to send data stream to the back-end and get
the message containing the time
If IMS message received from back-end system
SEND message to front-end terminal
RETURN
Build data for front-end terminal map
SEND map data to front-end terminal
RETURN TRANSID(CZPS) with COMMAREA
SEND-NEW-MAP routine:
SEND new map
RETURN TRANSID(CZPS) with COMMAREA
END-PROG routine:
Clear front-end terminal
RETURN
This sample program demonstrates using FEPI to obtain data from an IMS back-end transaction. It is in pseudoconversational style, using the FEPI START command to schedule itself when the results arrive.
Module names: DFH0VZPA, DFH0AZPA
Transaction name: CZPA
Map names: DFH0MZ5, DFH0MZ9
CZPA SLUP Sample Program. IMS SLUP Pseudoconversational sample program This transaction will process SEND/START/RECEIVE requests with MFS specified, to a back-end IMS system. DATE : 02/04/92 TIME : 10:58:50 STATE : Not Started F3=EXIT to CICS ENTER=obtain time and date stamp from IMS
On the first invocation of the program, a map is sent to the front-end terminal.
When there is input from the front-end terminal, CICS invokes the program again. After establishing a conversation, an inquiry is sent to the back-end system. FEPI START is issued to start this program again when the results arrive. Meanwhile it returns to CICS, so releasing resources.
When the results arrive, FEPI starts the program again. The results are obtained using FEPI RECEIVE, and sent on to the front-end terminal. The conversation is freed and the program returns to CICS to await more input. If the back-end system sends an IMS message, it is sent on to the front-end terminal and the transaction ends.
When PF3 or CLEAR is received from the front-end terminal, the transaction ends. If there is an error, the front-end map is reset. These situations are detected using HANDLE CONDITION.
For clarity, error checking is minimal except for the FEPI commands.
MAIN procedure:
If started from terminal
Test COMMAREA
If transaction not previously invoked
Call SEND-NEW-MAP
Set up exception condition handling:
Map error - SEND-NEW-MAP
CLEAR/PF3 - END-PROG
RECEIVE map from front-end terminal
FEPI ALLOCATE conversation with back-end system
Build SLU P data stream to request time
FEPI SEND data stream to back-end system
FEPI START transaction
RETURN
If started by FEPI
RETRIEVE start data
Reaccess conversation using FEPI ALLOCATE PASSCONVID
If EVENTTYPE = data received
FEPI RECEIVE data stream from back-end system
FEPI FREE conversation
If IMS message received
SEND message to front-end terminal
RETURN
Build data for front-end terminal map
SEND map to front-end terminal
RETURN TRANSID(CZPA) with COMMAREA
Otherwise (timeout or session loss)
SEND map with message to front-end terminal
RETURN (freeing conversation implicitly)
SEND-NEW-MAP routine:
SEND new map
RETURN TRANSID(CZPA) with COMMAREA
END-PROG routine:
Clear front-end terminal
RETURN
This program handles STSN processing for the FEPI sample application programs.
Module name: DFH0AZQS
Transaction name: CZQS
TS queue name: SESSION
This transaction is started by FEPI when a request for message resynchronization (‘set and test sequence number’, STSN) or a ‘start data traffic’ indication is received from a back-end IMS system.
The conversation passed by FEPI must be accessed so that FEPI knows that the event is being handled. The processing required depends on the STSN status, which is obtained using FEPI EXTRACT STSN.
For STSNSTATUS=NOSTSN, the transaction was started because ‘start data traffic’ arrived. A DR1 normal response must be sent.
For STSNSTATUS=STSNSET, a positive STSN response must be sent.
For STSNSTATUS=STSNTEST, processing would typically involve comparing saved sequence numbers with those received from the back-end IMS system to determine what response to send. The IMS Customization Guide gives advice on the appropriate action.
After the processing, the response is sent using FEPI ISSUE. A report is written to a TS queue named SESSION, which can be browsed using CEBR. The general format of the TS queue records is:
date time CZQS STSN processing completed
Target......TGTNAME Node........NODENAME
Seqnumin....nnnn Seqnumout...nnnn
STSN status.XXXXXXX Response....XXXXXXXX
Main procedure:
RETRIEVE start data
Access conversation using FEPI ALLOCATE with PASSCONVID
Get STSN status using FEPI EXTRACT STSN
Call NOSTSN, STSNSET, or STSNTEST
according to STSN status
Send response using FEPI ISSUE CONTROL
Write event details to TS queue
Free conversation, keeping session
RETURN
NOSTSN routine:
Build DR1 normal response
STSNSET routine:
Build STSN positive response
STSNTEST routine:
Handle as required
Build required response
[[ Contents Previous Page | Next Page Index ]]