Table of Contents Previous Next PDF


The Simple App Application
The Simple App Application
Introducing the Simple App Application
Purpose
The Simple App application is intended to be used:
•
To validate Oracle Tuxedo Application Rehosting Workbench installation.
•
To validate the whole migration process – from the source platform to the target platform.
Composition
The simple Sample Application contains batch and online processing coded in the following languages:
•
COBOL for batch and online programs.
•
CICS for online programs.
•
VSAM in batch and online program.
•
JCL for jobs (plus the IDCAMS and SORT utilities).
Each program is intended to be as simple as possible, the purpose of this application is not to demonstrate all of the features of Oracle Tuxedo Application Rehosting Workbench.
Usage
The overall process for using the Simple App application is:
1.
Install Oracle Tuxedo Application Rehosting Workbench environment.
2.
Install the Simple App source platform files.
3.
Convert the Simple App components.
4.
Install Oracle Tuxedo Application Runtime for CICS and Batch environment.
5.
Run the Simple App batch programs.
6.
Run the Simple App transactional programs.
Structure
The Simple App has the following structure:
Figure 3‑1 Simple App Structure
Description of the Simple App Components
This section describes the Simple App component architecture and the online and batch interactions.
Figure 3‑2 Simple App Coponent Architecture
 
List of Components by Type
CICS Screens
Name
Description
MAPM000
Customer maintenance entry menu.
MAPM001
Customer data inquiry screen.
MAPM002
Customer data maintenance screen (new customer, update and delete customer).
MAPM003
Customer list screen.
CICS Programs
Name
Description
PGMM000
Customer maintenance entry program.
PGMM001
Customer data inquiry program.
PGMM002
Customer data maintenance program (new customer, update and delete customer).
PGMM003
Customer list program.
Batch Programs
Name
Description
PGMMB00
Initial load of the VSAM file. This file is loaded from a QSAM file.
PGMMB01
This program produces a list of the customers stored in the VSAM customer file.
PGMMB02
This program accesses a QSAM file containing commands and data used to update the main VSAM customers file.
Transaction Codes
Name
Description
M000
Main entry transaction code (program PGMM000).
M001
Customer inquiry (program PGMM001).
M002
Customer maintenance (program PGMM002).
M003
Customer list (program PGMM003).
Jobs
Name
Description
DEFVCUST
This job runs an IDCAMS utility in order to DELETE & DEFINE the VSAM customer file.
CHKVCUST
This job runs an IDCAMS utility and REPRO the VSAM file into a QSAM which can be easily read and checked.
LODVCUST
This job runs the PGMMB00 batch program which reads a sequential file containing data to be stored in the newly defined VSAM customer file.
PRTVCUST
This job runs the PGMMB01 batch program which produces a report of the customers referenced in the VSAM file.
UPDVCUST
This job runs the PGMMB02 batch program which contains data used to update the VSAM customer file.
Map Descriptions
Listing 3‑1 MAPM000 - Simple App Main Menu
....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
MAPM000 Simple sample application 07/17/2009
M000
-------------------------------------------------------------------------------
Customer’s identifier: àààààà
PF04 – Customer’s List
PF05 – Add a new customer
PF06 – Modify an existing customer
PF07 – Delete an existing customer
PF08 – Customer’s inquiry
PF03 – Quit application
-------------------------------------------------------------------------------
Info: Type a customer number, select an action and press Enter.
-------------------------------------------------------------------------------
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
Listing 3‑2 MAPM003 - Customer list
....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
MAPM003 Customers list 07/17/2009
M003
 
-------------------------------------------------------------------------------
Sel ID Last name First name Birth date
-------------------------------------------------------------------------------
 
@ @@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@ @@/@@/@@@@
@ @@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@ @@/@@/@@@@
@ @@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@ @@/@@/@@@@
@ @@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@ @@/@@/@@@@
@ @@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@ @@/@@/@@@@
@ @@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@ @@/@@/@@@@
@ @@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@ @@/@@/@@@@
@ @@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@ @@/@@/@@@@
@ @@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@ @@/@@/@@@@
@ @@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@ @@/@@/@@@@
 
 
-------------------------------------------------------------------------------
-PF7: Page up -PF8: page down -PF3: return to previous menu
-Info: Enter a non blank character and press enter to view customer's data
-------------------------------------------------------------------------------
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
Listing 3‑3 MAPM001 - Customer detailed information
....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
MAPMM01 Customer's detailed information 07/17/2009
M001
 
-------------------------------------------------------------------------------
Customer's identifier: àààààà
-------------------------------------------------------------------------------
-Last name_____: àààààààààààààààààààààààààààààà
-First name____: àààààààààààààààààààà
-Address_______: àààààààààààààààààààààààààààààà
-City__________: àààààààààààààààààààà
-State_________: àà
-Birth date____: àà/àà/àààà
-Email_________: àààààààààààààààààààààààààààààààààààààààà
-Phone number__: àààààààààà
 
-------------------------------------------------------------------------------
-PF03: return to previous screen
-------------------------------------------------------------------------------
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
Listing 3‑4 MAPM002 - Customer maintenance
....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
MAPM002 Customer's maintenance 07/17/2009
M002
 
-------------------------------------------------------------------------------
Customer's identifier: àààààà Action: @@@@@@
-------------------------------------------------------------------------------
 
-Last name_____: àààààààààààààààààààààààààààààà
-First name____: àààààààààààààààààààà
-Address_______: àààààààààààààààààààààààààààààà
-City__________: àààààààààààààààààààà
-State_________: àà
-Birth date____: àà/àà/àààà
-Email_________: àààààààààààààààààààààààààààààààààààààààà
-Phone number__: àààààààààà
 
-------------------------------------------------------------------------------
-PF11: clear screen
-PF12: confirm action
-PF03: return to previous screen
-------------------------------------------------------------------------------
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
Program Descriptions
CICS Program Descriptions
PGMM000 (customer maintenance main menu)
PGMM000 is the Simple Sample Application (access) main menu program. From this screen, one may access the following functions:
•
Customer list
•
Customer detailed information inquiry
•
Customer data maintenance:
•
Add a new customer
•
Update customer information
•
Delete an existing customer
Each function can be reached by entering a specific function key. At the end of the called function, a return is performed back to this main menu.
Controls:
This program checks that a valid customer identification number is entered when accessing the inquiry and maintenance functions.
PGMM001 (customer detailed information inquiry)
This program receives – thru the communication area – a customer identification number. The program accesses the VSAM customer file in order to display the customer data when known.
Controls:
Assuming that no data can be modified by this program, no control is performed.
PGMM002 (customer data maintenance)
This program enables the maintainance of the VSAM customers file:
•
Creating a new customer
•
Updating an existing customer
•
Deleting an existing customer
PGMM002 receives an action code and, when needed, a customer identification number. The action to be performed is displayed on the screen (CREATE, UPDATE or DELETE).
Controls:
The controls carried-out depend on the action to perform.
When creating a new customer, the programs checks that:
•
The Customer identification number is not null, is numeric and not already used in the customer VSAM file.
•
Last name, first name, address, city, email address and birth date are not equal to spaces.
•
Phone number, if not equal to zero, must be numeric.
When updating an existing customer, the controls are the same as the ones used when creating a customer except for the customer identification number, which cannot be modified.
There is no control performed on a customer deletion request.
PGMMM03 (customer list)
This program lists the customers stored in the VSAM file. A limited number of customers are displayed on each screen – the PF7 and PF8 keys give access to the previous and next pages. A non-blank character at the beginning of a customer's line gives access to the detailed customer information screen (see program PGMM001).
Batch Program Descriptions
PGMMB00 (VSAM file initial load)
This batch program reads a sequential file containing data to be stored in the VSAM file. For each record in the entry file, a VSAM record is created. The VSAM file must have been DELETED and DEFINED prior to executing this program. All data from the entry file is supposed to be valid: hence, no control is performed within this program.
PGMMB01 (customer report)
PGMMB01 reads all the customer record from the VSAM file and produces a report. An example of the report produced is included in this document.
PGMMB02 (batch customer maintenance program)
Each input sequential file record contains a three characters action code (ADD, UPD or DEL) and the customer data required when creating a new customer or updating an existing one. Each input line updates the VSAM customer file. Customer data from the sequential file is supposed to be valid so that no control is performed by the PGMMB02 batch program.
Simple App Functionalities
Batch Processing
Batch programs and utilities are used to populate, update and list the VSAM customer file that hosts the data managed within the application. Five jobs are delivered with the application. This chapter describes how they are used.
VSAM customers file initial load
1.
Step 1: VSAM file definition
First, define the VSAM customer file thru the IDCAMS utility using DELETE/DEFINE commands.
2.
Step 2: VSAM file initial load
The batch program PGMMB00 is used to populate the VSAM file.
3.
Step 3: VSAM file check
IDCAMS is used to REPRO the VSAM file into a sequential file which can easily be read in the z/OS environment.
4.
Step 4: VSAM file report
Batch program PGMMB01 produces a list of the customers stored in the VSAM customer file.
Figure 3‑3 VSAM customers file Initial load
VSAM customer file update
1.
Step 1: VSAM file update
Batch program PGMMB02 reads a sequential file containing updates to be performed on VSAM customers file. The input file is sorted by the IBM standard sort utility.
2.
Step 2: VSAM file report
Batch program PGMMB02 is used again in order to check that the updates were correctly applied to the VSAM customers file.
Figure 3‑4 VSAM file update
Data description
Simple Sample Application relies on only one VSAM main customer file. In order to keep the migration process as simple as possible, the data is stored in displayable formats (in COBOL syntax, this means that only "X" and "9" USAGE DISPLAY pictures are used).
The VSAM customer file contains the following information:
Table 3‑1 VSAM Customer Fle Description
Name
Type
Length
Description
CUSTIDENT
Num.
6
Customer identification number
CUSTLNAME
Alpha
30
Customer last name
CUSTFNAME
Alpha
20
Customer first name
CUSTADDRS
Alpha
30
Customer address (street…)
CUSTCITY
Alpha
20
City
CUSTSTATE
Alpha
2
State
CUSTBDATE
Num.
8
Customer birth date
CUSTEMAIL
Alpha
40
Customer email address
CUSTPHONE
Num.
10
Customer phone number
This VSAM file is a Key Sequenced Data Set (KSDS) based on the customer's identification number. Each record contains 266 characters and the key is stored from position 1 to position 6.
VSAM customer file COBOL description
Listing 3‑5 VSAM customer file COBOL description
01 ODCSF0-RECORD.
05 CUSTIDENT PIC 9(006).
05 CUSTLNAME PIC X(030).
05 CUSTFNAME PIC X(020).
05 CUSTADDRS PIC X(030).
05 CUSTCITY PIC X(020).
05 CUSTSTATE PIC X(002).
05 CUSTBDATE PIC 9(008).
05 CUSTBDATE-G REDEFINES CUSTBDATE.
10 CUSTBDATE-CC PIC 9(002).
10 CUSTBDATE-YY PIC 9(002).
10 CUSTBDATE-MM PIC 9(002).
10 CUSTBDATE-DD PIC 9(002).
05 CUSTEMAIL PIC X(040).
05 CUSTPHONE PIC 9(010).
05 FILLER PIC X(100).
 
Report Layouts
The following report is produced by program PGMMB01 that lists the customers from the VSAM file (METAW00.VSAM.CUSTOMER) after the initial load.
Listing 3‑6 Simple App Initial Report
PGMMB01 Simple Sample Application 07/16/2009
 
_ ID _ _ LAST NAME _ _ FIRST NAME _ _ CITY _ _ PHONE _ _B. DATE _
------ ----------------------------------- -------------------- ---------- ----------
1 Richardson Bobby New Orleans 5553557901 09/07/1961
2 Roberts Sammy San Francisco 5559827383 01/24/1973
3 Douglas Burt Atlanta 5556531100 10/12/1981
4 Ewing Samantha New York 5558762763 07/27/1962
5 Prince Anne Fresno 5553410156 12/25/1991
 
PGMMB01 Simple Sample Application 07/16/2009
 
_ ID _ _ LAST NAME _ _ FIRST NAME _ _ CITY _ _ PHONE _ _B. DATE _
------ ------------------------------ -------------------- -------------------- -------
6 Colombus Christopher Colombus 5557811021 07/27/1962
7 Raul Menedez Fresno 5558981572 07/27/1962
8 Doors Bill Seattle 5553122000 01/01/1958
9 Awing Charles San antonio 5559990123 06/29/1929
 
 
The following report is based upon the updated customer file.
Listing 3‑7 Simple App Updated Customer File Report
PGMMB01 Simple Sample Application 07/16/2009
 
_ ID _ _ LAST NAME _ _ FIRST NAME _ _ CITY _ _ PHONE _ _B. DATE _
------ ----------------------------------- -------------------- ---------- ----------
1 Richardson Bobby New Orleans 5553557901 09/07/1961
2 Roberts Sammy Jr San Francisco 5559827383 01/24/1973
3 Douglas Burt Atlanta 5556531100 10/12/1981
4 Ewing Samantha New York 5558762763 07/27/1962
5 Prince Anne Fresno 5553410156 12/25/1991
_ ID _ _ LAST NAME _ _ FIRST NAME _ _ CITY _ _ PHONE _ _B. DATE _
------ ----------------------------------- -------------------- ---------- ----------
6 Colombus Christopher Colombus 5557811021 07/27/1950
8 Doors Bill Seattle 5553122000 01/01/1958
9 Awing Charles San antonio 5559990123 06/29/1929
10 Simms Arthur New Orleans 5551298373 01/17/1969
11 LaFayette Eric Plesanton 5554653213 02/12/1995
12 Jackson Mic Fresno 5559800727 01/01/1959
 
Using the Simple App Application
This section provides an example use of the Simple App Application in order to illustrate how to use the application.
Viewing A Customer Record
1.
Access your CICS environment and enter the Simple App main transaction code M000 to connect to the application.
2.
The Main menu is dispalayed. Enter 000003 in the Customer identifier field and press the PF08 key to inquire on the customer.
3.
The customer record of Douglas Burt is displayed. Press PF03 to return to the Main menu.
Updating A Customer Record
1.
From the Main menu enter 000003 in the Customer identifier field and press the PF06 key to update customer information.
2.
In the update screen all data may be modified. The screen header shows the action UPDATE. Change the customer’s address and press ENTER.
3.
Press PF12 to confirm the updates. A Maintenance OK messageis displayed in the screen footer. To cancel your input, press PF03 in order to return to the Main menu.
Printing Customer Reports
1.
From the Main menu, press PF04 to access the Customer List first page.
2.
Press PF08 to display the next page in the list. Press PF07 to display a previous page in the list.
Note:
You can perform a customer inquiry by entering any non-blank character in the selection (Sel) column to the lft of each customer.
Adding New Customers
1.
From the Main menu press PF05, the following screen is displayed.
Action is set to CREATE in the screen header and fields are unprotected.
2.
Enter the new customer data including a valid non-existing identifier, and press ENTER.
The program validates the record; when no errors are found, a confirmation message is displayed.
3.
Press PF12 to create a new customer record.
A New customer added message is displayed.
4.
Press PF03 to return to the main menu.
Simple App APIs
This section lists the CICS APIs which are used within the Simple App application programs.
MAP APIs
SEND
EXEC CICS
SEND MAP('MAPM000') MAPSET('MAPM000') ERASE
END-EXEC.
EXEC CICS
SEND MAP('MAPM000') MAPSET('MAPM000') CURSOR ERASE
END-EXEC.
EXEC CICS
SEND MAP('MAPM001') MAPSET('MAPM001') FROM(MAPM001O) ERASE
END-EXEC.
RECEIVE
EXEC CICS
RECEIVE MAP('MAPM000') MAPSET('MAPM000')
END-EXEC.
EXEC CICS
RECEIVE MAP('ORDMAP1') MAPSET('ORDSET1') INTO(ORDMAP1)
END-EXEC.
NAVIGATION APIs
RETURN
EXEC CICS
RETURN
END-EXEC.
EXEC CICS
RETURN TRANSID('M000') COMMAREA(COMM-RECORD)
LENGTH(LENGTH OF COMM-RECORD)
END-EXEC.
XCTL
EXEC CICS
XCTL PROGRAM(PGM-DEST) COMMAREA(COMM-RECORD)
LENGTH(LENGTH OF COMM-RECORD)
END-EXEC.
ABEND
EXEC CICS
ABEND ABCODE('META')
END-EXEC.
VSAM APIs
STARTBR
EXEC CICS STARTBR DATASET ('ODCSF0')
RIDFILD (CUST-FILE-KEY)
EQUAL
RESP (RESPONSE-CODE)
END-EXEC.
EXEC CICS STARTBR DATASET ('ODCSF0')
RIDFILD (CUST-FILE-KEY)
GTEQ
RESP (RESPONSE-CODE)
END-EXEC.
READ
EXEC CICS
READ FILE('ODCSF0')
INTO(VS-ODCSF0-RECORD)
RIDFLD(CUST-FILE-KEY)
LENGTH(LENGTH OF VS-ODCSF0-RECORD)
EQUAL
RESP(RESPONSE-CODE)
END-EXEC.
EXEC CICS READ DATASET ('ODCSF0')
INTO (READ-ODCSF0-RECORD)
LENGTH (LENGTH OF READ-ODCSF0-RECORD)
RIDFLD (CUST-FILE-KEY)
EQUAL
UPDATE
RESP (RESPONSE-CODE)
END-EXEC.
WRITE
EXEC CICS WRITE DATASET ('ODCSF0')
FROM (MAJ-ODCSF0-RECORD)
LENGTH (LENGTH OF MAJ-ODCSF0-RECORD)
RIDFLD (MAJ-CUSTIDENT)
KEYLENGTH (6)
RESP (RESPONSE-CODE)
END-EXEC.
REWRITE
EXEC CICS REWRITE DATASET ('ODCSF0')
FROM (READ-ODCSF0-RECORD)
LENGTH (LENGTH OF READ-ODCSF0-RECORD)
RESP (RESPONSE-CODE)
END-EXEC.
READNEXT
EXEC CICS READNEXT DATASET ('ODCSF0')
INTO (CLT-ODCSF0-RECORD)
LENGTH (LENGTH OF CLT-ODCSF0-RECORD)
RIDFLD (CUST-FILE-KEY)
RESP (RESPONSE-CODE)
END-EXEC.
READPREV
EXEC CICS READPREV DATASET ('ODCSF0')
INTO (CLT-ODCSF0-RECORD)
LENGTH (LENGTH OF CLT-ODCSF0-RECORD)
RIDFLD (CUST-FILE-KEY)
RESP (RESPONSE-CODE)
END-EXEC.
ENDBR
EXEC CICS ENDBR DATASET ('ODCSF0')
END-EXEC.
DELETE
EXEC CICS DELETE FILE ('ODCSF0')
RIDFLD (CUST-FILE-KEY)
RESP (RESPONSE-CODE)
END-EXEC.
MISCELLEANOUS APIs
TIME
EXEC CICS
ASKTIME ABSTIME(ABS-TIME)
END-EXEC.
EXEC CICS
FORMATTIME ABSTIME(ABS-TIME)
DDMMYY(VDATEO) DATESEP('-')
END-EXEC.
HANDLE CONDITIONS
EXEC CICS
IGNORE CONDITION MAPFAIL
END-EXEC.
EXEC CICS
HANDLE CONDITION PGMIDERR(PGM-NOTFOUND)
END-EXEC.
Simple App Documentation References
You may find a detailed description of the CICS APIs at the following address:
http://publib.boulder.ibm.com/infocenter/cicsts/v3r1/index.jsp?topic=/com.ibm.cics.ts31.doc/dfhp4/topics/dfhp4_commands.htm
Detailed Description of the CICS APIs
The following CICS APIs are used in the Simple App application.
Table 3‑2 Simple App CICS APIs
API
Description
ASKTIME
Request current date and time of day.
DELETE
Delete a record from a file - VSAM KSDS, VSAM RRDS, and data tables only.
ENDBR
End browse of a file.
FORMATTIME
Transform absolute date and time into a specified format.
LINK
Link to another program expecting return. The external CICS interface (EXCI) provides a LINK command that performs all six commands of the interface in one invocation. See the CICS External Interfaces Guide for information about the EXCI.
READ
Read a record from a file.
READNEXT
Read next record during a browse of a file.
READPREV
Read previous record during a file browse; VSAM and data tables only.
RECEIVE MAP
Receive screen input into an application data area. For further information about BMS, see the
RETURN
Return program control.
REWRITE
Update a record in a file.
SEND MAP
Send mapped output data to a terminal. The keywords are separated into those supported by minimum, standard, and full BMS. For further information about BMS, see the CICS Application Programming Guide.
START
Start task at a specified time.
STARTBR
Start browse of a file.
WRITE
Write a record.
XCTL
Transfer program control.
This document is based upon the following reference guide: CICS Transaction Server for z/OS Application Programming Reference
 

Copyright © 1994, 2017, Oracle and/or its affiliates. All rights reserved.