The Sale example application

The Sale example application is a sample BTS application that you can set up to see the workings of a business transaction. The business transaction has four basic actions; order entry, delivery, invoice, and payment. It also includes some more advanced BTS features.

About the Sale example application

A Sale business transaction is started by a terminal-user selecting the Sale option from a menu of business transactions. This selection causes an instance of the transaction to be created and its root activity to be started. The root activity creates and runs, in sequence, four child activities that implement the four actions of the business transaction:
  1. The Order activity obtains order data from the user, and validates it.
  2. Successful completion of the Order activity causes the Delivery activity to be started.
  3. Completion of the Delivery activity causes the Invoice activity to be started.
  4. When payment is received and recorded by the Payment activity, the Sale business transaction is complete.

Figure 1 shows, in simplified form, data flows in the Sale example application.

Figure 1. Data flow in the Sale example application. (The root activity is not shown.)
The diagram shows the data flows of user input data and output data. A rectangle represents the Sale business transaction. The rectangle contains four smaller rectangles, representing the Order, Delivery, Invoice, and Payment child activities. Another rectangle, outside the Sale transaction, represents the Menu transaction. Input and output data flows are represented by arrows. The Menu transaction collects input from the user. The output from the Menu transaction becomes the input to the Order activity. The Order activity collects further input from the user. The output from the Order activity becomes the input to the Delivery activity. The output from the Delivery activity becomes the input to the Invoice activity. The output from the Invoice activity becomes the input to the Payment activity.
  1. Customer data (for example, an account number) collected after the terminal user selects the Sale menu option is used as input to the Order activity.
  2. Customer data collected by the Order activity is used as input to the Delivery activity.
  3. The output data produced by the Delivery activity is used as input to the Invoice activity.
  4. The output produced by the Invoice activity is used as input to the Payment activity.

The first activity (Order) requires input from the terminal user. Subsequent activities (Delivery, Invoice and Payment) are assumed not to require any user involvement and are triggered serially in the background after the Order activity has completed successfully. This assumption can be changed to illustrate additional function.

The Sale example application: CICS transactions, programs, and copybooks

The Sale application uses category 3 sample transactions and sample programs. The copybooks, maps, and map sets are also supplied with CICS, and the source modules are fully annotated with explanatory comments.

The sample is implemented as a set of COBOL programs. These programs are supplied, in source code, in the SDFHSAMP library, together with copybooks and BMS maps and map sets. The resource definitions are in an RDO group DFH$CBTS.

The sample uses a repository file called DFHBARF. RDO group DFH$BARF contains a definition of DFHBARF. For an example of the JCL that you might use to create a repository, see Repository data sets.
Note: The supplied definition of DFHBARF uses LSRPOOL 1. Ensure that LSRPOOL 1 is defined on your system with a MAXKEYLENGTH of at least 50.

Table 1 shows the CICS® transactions and programs that make up the application.

Table 1. Transactions and programs in the BTS sample application
Transaction Program Function
SALM DFH0SAL0 Order entry. The order entry transaction is a regular CICS transaction running outside the BTS environment.
SAL1 DFH0SAL1 Accepts the order and defines and runs the SALE process.
SALE DFH0SAL2 The root activity of the SALE process. This is the main logic-control program. It defines and runs the following activities:
  • Customer credit-check, run synchronously with the root activity
  • Stock check, run synchronously
  • Delivery note, run asynchronously
  • Invoice, run asynchronously
  • Payment-not-received reminder, run asynchronously (if payment is not received before the timer expires).
RED1 DFH0RED1 Implements the customer credit-check activity.
STOC DFH0STOC Implements the stock-level check activity.
DEL1 DFH0DEL1 Implements the delivery note activity.
INV1 DFH0INV1 Implements the invoice activity.
REM1 DFH0REM1 Implements the payment-not-received reminder activity.
PAYM DFH0PAY0 Payment input. The payment input transaction is a regular CICS transaction running outside the BTS environment.
PAY1 DFH0PAY1 Accepts the payment information, then acquires and runs the appropriate SALE process. This causes the SALE process to complete.

Table 2 shows the copybooks, maps, and map sets that are supplied with the sample application.

Table 2. Copybooks, maps and map sets supplied with the BTS sample application
Type Member Description
Copybook DFH0CONT Container definitions.
Copybook DFH0SALC Defines BMS map fields for the SALM transaction.
Copybook DFH0PAYC Defines BMS map fields for the PAYM transaction.
Map/Mapset DFH0SALM Source of the BMS map for the SALM transaction. The map set is DFH0SAS. The name of the map is ORDER.
Map/Mapset DFH0PAYM Source of the BMS map for the PAYM transaction. The map set is DFH0PAS. The name of the map is PAYMENT.

You can use the sample as the basis of your own sales application. However, before using it in a production environment, you must add installation-specific code.

Important: Sample program DFH0SAL2 contains the following command:
 EXEC CICS DEFINE ACTIVITY('CREDIT-CHECK')
                  TRANSID('RED1')         
                  PROGRAM('DFH0RED1')     
                  USERID('USER0001')      
                  RESP(RESP-AREA)         
                  RESP2(RESP2-AREA)       
 END-EXEC.

You must change the value of the USERID option to specify a user ID that is valid in your installation. You must enter the customer number and order number because they are used by the DEFINE PROCESS command. The PROCESS must have a unique name.

Running the sample application from a web browser

You can run the sample application from a web browser. The DFH0SAL0 program source code contains detailed instructions about how you can put a web front end on to the two BTS processes used in the sample.