Description of the samples

Setup

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

Overview

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.

Program logic

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

Monitor and unsolicited data-handler

This program monitors unexpected events and handles unsolicited data for the FEPI sample programs.

Module name: DFH0VZUX

Transaction name: CZUX

TS queue name: MONITOR

Overview

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.

Program logic

  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

Begin session

This program prepares sessions for use by the FEPI sample application programs.

Module name: DFH0VZUC

Transaction name: CZUC

TS queue name: SESSION

Overview

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.

Program logic

  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

Key stroke 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

Screen

Figure 11. CZTK transaction: customer name and address inquiry
 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

Overview

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.

Program logic

  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

Screen image SEND and START

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

Screen

Figure 12. CZTS transaction: customer name and balance inquiry
 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

Overview

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.

Program logic

  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

Screen image RECEIVE and EXTRACT FIELD

This sample program demonstrates using FEPI to get formatted data from a back-end transaction.

Module name: DFH0VZTR

Transaction name: CZTR

Map name: DFH0MZ2

Screen

See Figure 12.

Overview

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.

Program logic

  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

3270 data stream pass-through

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

Overview

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.

Program logic

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

End-session handler

This program cleans up sessions after use by FEPI sample application programs.

Module name: DFH0VZUU

Transaction name: CZUU

TS queue name: SESSION

Overview

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.

Start of changeThe 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.End of change

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

Program logic

  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

SLU P one-out one-in

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

Screen

Figure 13. CZPS transaction: SLU P sample program
 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

Overview

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.

Program logic

  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

SLU P pseudoconversational

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

Screen

Figure 14. CZPA transaction: SLU P pseudoconversational sample program
 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

Overview

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.

Program logic

  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

STSN handler

This program handles STSN processing for the FEPI sample application programs.

Module name: DFH0AZQS

Transaction name: CZQS

TS queue name: SESSION

Overview

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

Program logic

   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 ]]