1	Enterprise COBOL Education Using Rational Developer for System Z COBOL Report Writing Patterns Jon Sayles, IBM Software Group, Rational EcoSystems Team
2	IBM Trademarks and Copyrights © Copyright IBM Corporation 2007,2008. All rights reserved. The information contained in these materials is provided for informational purposes only, and is provided AS IS without warranty of any kind, express or implied. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, these materials. Nothing contained in these materials is intended to, nor shall have the effect of, creating any warranties or representations from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of IBM software. References in these materials to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates. This information is based on current IBM product plans and strategy, which are subject to change by IBM without notice. Product release dates and/or capabilities referenced in these materials may change at any time at IBM’s sole discretion based on market opportunities or other factors, and are not intended to be a commitment to future product or feature availability in any way. IBM, the IBM logo, the on-demand business logo, Rational, the Rational logo, and other IBM Rational products and services are trademarks or registered trademarks of the International Business Machines Corporation, in the United States, other countries or both. Other company, product, or service names may be trademarks or service marks of others.
3	Course Contributing Authors Thanks to the following individuals, for assisting with this course: Bill Klein, Stephen Heffner/Pennington Associates
4	Purpose of This Document Course Name: COBOL Foundation Training - with RDz Course Description: Learn the COBOL language, RDz and learn z/OS terms, concepts and development skills in this course. Pre-requisites: Some experience in a 3rd or 4th Generation Language is expected. SQL is also recommended. Course Length: 10 days Topics (Agenda) Getting Started - installing and configuring RDz - and the course materials, and using Eclipse to edit COBOL COBOL General Language Rules Basic COBOL Statements Advanced record and table handling Debugging Programs - Note: Deep dive on using RDz for common COBOL programming errors (001, 0C4, 0C7, infinite loops, fall-thru, etc.) Input/Output and Report Writing Patterns COBOL Subprograms and the Linkage Section Structured Programming Concepts, professional COBOL development practices and Coding Patterns Advanced Character Manipulation, COBOL Intrinsic Functions, Date and Time coding patterns, and Language Environment calls OS/390 Concepts and JCL - Compile/Link & Run Procs on the mainframe Indexed file Coding Patterns Sort/Merge, Sequential File Match/Merge and Master File Update Coding Patterns Accessing DB2 Data and DB2 Stored Procedures COBOL in the Real World: CICS - lecture only IMS (DL/I and TM) - ditto Batch processing - ditto Java calling COBOL COBOL and XML Statements SOA and COBOL - creating and calling Web Services Web 2.0 using Rich UI
5	Course Details Audience This course is designed for application developers who have programmed in some language before, and who wish to learn COBOL. Prerequisites This course assumes that the student has the basic knowledge of IS technologies, data processing, software and have programmed for at least two or more years in a language such as: Java, VB, RPG, PL/1, Pascal, or some 4^th Generation Language or tool. Knowledge of SQL (Structured Query Language) for database access is assumed as well. Basic PC and mouse-driven development skills is also assumed. Finally, it is assumed that you have been following along in this course, and have successfully completed the learning modules in sequence. Or have the equivalent COBOL background obtained through some other form of COBOL study or on-the-job work.
6	COBOL Report Writing Patterns
7	COBOL Reporting – a Little History Since its inception (the late 1950's) COBOL has been the dominant language of business application development For the first 30-40 years (yes, a COBOL application's shelf-life measure in decades what some application languages aspire towards, measured in years) businesses founded on COBOL used the language for: Data capture and storage – using: Sequential files Indexed files Hierarchical databases Networked (CODASYL) and other pointer-based databases (such as Model 204) Relational databases Object databases Reporting applications – both broad and deep, used in every aspect of the business world Online applications Batch (non-reporting) applications – data consolidation, computationally intensive applications, etc Internet application Now in its 6th decade, COBOL applications still do all of the above – but certainly not in the same ratio and proportion they did in the 70's, 80's and 90's In fact, one type of COBOL business application that is only marginally as important as it was in the past is the reporting application – specifically traditional print reports or "green bar" reports (See Slides)
8	Why Learn About COBOL Reporting Applications Traditional reporting applications consumed a large portion of early COBOL practitioner time and attention The COBOL language even has a REPORT SECTION – in the DATA DIVISION that provides special keyword vocabulary for creating reports Business reports in fact were so critical to commercial shops that throughout the 1970's à 1990's dozens of high-quality reporting products emerged on the market to simplify and streamline report development Some by IBM Many, many, many others – by 3rd Party IBM Business Partners *** See Slide Notes The reason for these non-COBOL/3rd Party products was that essentially, Reporting Applications written in any general-purpose 3rd generation computing language: Are time-consuming and labor-intensive to create Can be built from special-purpose tools and using proprietary report-programming languages: Quickly Cost-effectively Often are time-dependent, in that unlike data, which has intrinsic and lasting value to organizations, reports are essential "the original" U.I. of business applications And U.I.s have changed drastically since 1960 – haven't they While the production source-code assets represented by the 3rd Party products have not necessarily maintained their position, you will still most likely find the knowledge of how create COBOL reports useful for the following reasons: You may end up writing a "quick-and-dirty" report against production data (these are sometimes called "one-offs" You will most likely have to maintain and/or support COBOL reporting applications still running in production.
9	COBOL Reporting Applications – Big Picture The figure below shows a typical COBOL reporting application, which contains the following elements: A sorted sequential data source – one of the following: On the mainframe a QSAM file – on the PC a "flat file" or sequential file One the mainframe a VSAM or off the mainframe an indexed file – read sequentially A database (IMS-DL/I, CA-IDMS, DB2, or other) read sequentially A program that processes records from the data source: Read file – usually sequentially, until end-of-file Validate/Compute each record, move fields Write report – that there are a few new COBOL WRITE clauses specific to reporting applications A report – or report file, that is laid out according to precise U.I. record descriptions And quite possibly a file of error records, produced by the COBOL program's validation routine We continue by looking at each part of the above
10	Sequential Input Files – For COBOL Reporting Applications If you've been following along in this course you've already done a bit of work with Sequential Files. Which are simple data structures that store records serially Such that the records are read one after another These records can be sorted or un-sorted. We will cover sorting in an upcoming unit COBOL Reports will just about always require the data to be sorted, and we will discuss various means of doing that in subsequent course sections: COBOL internal sort Operating System (JCL) sort 3rd Party Sort packages The data in the sorted sequential file records will be read into 01 record structures Typically READ <fileName> INTO <ws-RecordName>. The input record layouts correspond to the input data – which you've seen a number of times now 01 records Group fields (levels 05 and higher) Elementary fields, 88 levels, etc.
11	A Simple Report Have a look at this report è Let's break down the output or report-specific elements
12	Working Storage for the Simple Report From the code shown here è Match each of the 01s to the output shown (below) One 01 is not shown in the report You will add this in, when you do your work Answer the following questions: Why the VALUE SPACES next to the FILLER fields? Are the report columns lined up? What do you think the input for this report looks like?
13	: Input Data and Record Layout for the Simple Report*** See Slide Notes From the graphic below, note the input fields in the input file (Sorted Sequential File). Map each field to its respective variable in CustomerRec Answer the following questions: How many fields are there (total) – not counting the 10-level break out of the date field? Are any of the fields packed decimal or binary data? Is the data as shown, sorted? What "key" (what input field variable) is it sorted on Ascending or Descending sort?
14	Procedure Division for the Simple Report So – as this example is primarily: Read à Move to output file à Write we can assume the logic is relatively straightforward And? It is. Read the code shown here, and follow the flow of control. Note the following: File OPEN/CLOSE statements Initial report heading and file read statements Logic to perform the main business logic and report production paragraph until no more data. Within that paragraph: Check for page break condition Move statements from the input to the output variables Write detail line: AFTER ADVANCING LINE forces the printer to skip # lines between Read next input record Final Print Headings
15	:Workshop – Sequential File Processing – 1 of 7 As you have done several times so far, Create a new, Workstation Local, COBOL project Name it: chapter4 Be sure to select þ COBOL Sample Property Group In the chapter4 Project, create a new cobol folder (as shown) Copy the COBOL source code from the Notes section of the slide Create a new file in the chapter4 project, in the 1cobol folder, named: rpt1.cbl Paste the code in the editor Do a Local Syntax check of the program Right-click and Nominate rpt1 as the Entry Point Rebuild the chapter4 project Expand the BuildOutput folder, right-click and select Debug As > Debug Configurations Setup a new Debug Configuration as shown Debug the program Step to understand the code flow Resume (run) to end of program Look at the output file produced è (probably: c:\customerOut.dat)
16	:Workshop – Sequential File Processing – 2 of 7 – Maintenance Specs Â Let's throw in some new specs for a "maintenance" workshop. To complete the work required, you will need to: Edit the input records read. Only allow records with: Valid numeric CustomerIDs The year-in (YYYY) between 1990 and the current year You will have to ACCEPT the CURRENT DATE into an 8-byte date format (see code example in upcoming slide for an example of this) All records in error should be written to a new error output file – unformatted Add counters for: # of error records found # of Good error records written Total # of input records read – the sum of this should equal the # of error records + the number of good records*** See Notes Change Page Break to occur after 10 records Fix the bug in the Active/Inactive output value – currently it's only writing I or A, and should write out Inactive or Active See the next slide for an example new report Use the values in the slide notes for new input test records Sometimes known as test cases Please read through all of the Workshop Slides before beginning to code. Note the use of PERFORM … THRU EXIT – which simplifies modifying logic
17	:Workshop – 3 of 7 – Output Report Note the following: Page #s at the bottom of each page Statistics è
18	:Workshop – 4 of 7 – Environment and Data Division Note the following: New file Select/Assign and FD for the Error records Redefinition of CustomerID – in order to do a numeric Class test on it
19	:Workshop – 5 of 7 – Data Division and Procedure Division Note the following: New value for PageBrkReq New counters for records read/written, good, bad, indifferent, etc. Current-Date variable and Aceppt statement New file open/close/read/write Added EXIT statements to the 100- paragraph, to simplify maintaining the code
20	:Workshop – 6 of 7 Note the following: Code for adding to the various record counters New routine for handling the error records – inline within the current logic New input edit sample Note the use of the following logic pattern: Find an error Deal with the error Skip to the end of the function
21	:Workshop – Sequential File Processing – 7 of 7 Â Suggested course of action: Code the ENVIRONMENT, and DATA Division elements Syntax check and Build the Project Code the remaining PROCEDURE DIVISION logic Use Content Assist to help you code references to the fields and records This is why you'll do the data variable coding first J Syntax check Build the Project Debug your program Run your program – and verify your work by reviewing the output files If time permits, add the following new requirements: Additional Working Storage and output variables that count the # of Active and Inactive accounts Add the current date to the top right-hand corner of the page, in ISO format Move the page # to the top-left of each page
22	COBOL Report Writing Patterns
23	COBOL Report Writing Statements – WRITE AFTER ADVANCING Options The SPECIAL-NAMES paragraph: Relates IBM-specified environment-names to user-defined mnemonic-names. Relates alphabetic-names to character sets or collating sequences. Relates class names to sets of characters. Specifies a substitute character for the currency sign. In this example C01 is a "special name" that is used with the WRITE I/O verb, to skip to the top of the next page when the output file is attached to a printer that accepts files formatted for printing (i.e. with special characters for advancing to the next physical page, etc.). AFTER ADVANCING n LINES Is a clause of the WRITE statement, that directs the printer to advance the next physical line in the report paper Can specify AFTER or BEFORE LINES is optional Note the use of BEFORE ADVANCING 0 LINES – executed multiple times. This is used to make a header or bold on a report
24	:Workshop – Open Ended Â One more maintenance assignment. We now have to account for four quarters worth of taxes (this program is run at end-of-year). Replace the existing c:\customerIn.dat data, with the records in the Slide Notes Recode the input file's layout to match the new test case values Create an output report that matches the next slide's screen capture Add in one more statistic kept: Average annual taxes paid (see next slide for snapshot of result) You will have to be cognizant of: Numeric output formatted fields Lining up the columns of the report and the final average value
25	:Workshop – Open Ended
26	Workshop Coding Solution There is a coding solution to this simple report programming problem in the slide notes. Considerations: This is only one interpretation of how to do this workshop It is offered here as – Caveat Emptor If you choose to use this, we recommend you rename the program So that if you want to finish your own version of this workshop you won't have to rename files, etc. Optional Add the State values into the output print (Rpt-Detail-Hdg-1 and Rpt-Detail-Hdg-2) lines
27	COBOL Report Writing Patterns
28	What Are Control Breaks? A "Control Break" in COBL program vernacular, refers to a change in a control field value – typically in a sequential file, such that, upon successive reads when the value changes? A processing change happens in the program – and you would perform a routine that prints a control-break line containing: Summary values, sub-totals and/or statistics: Lines counted – for all of the records since the last control break Accumulators - numeric values such as: Number of items sold, Total expenses, etc. Statistics – average, min, max salaries, etc. The pre-requirement for Control Break functionality is for the sequential file to be sorted on the values in the control break field Or there would be random control breaks in the output processing Control Break reports are common in COBOL applications. They expose summary values and statistics, and help turn raw data into the information necessary to run a business. Show me the total sales for our retail stores broken out by: State Store Departments Months of the year Individual stores
29	Single-Level Control Break Report – Example Break on U.S. State Values Note that the "control break" occurs: Each time the State changes And at the end of the report (an implied final control break)
30	What Are Control Breaks? Do Initial Process Do Process All Records until end-of-file Do End-of-Program Process Initial Process Write headers Process first record Move control break field to a hold-area (for comparison) Process All Records Edit – or Do Edit Routine If good record If Current control-break-value <> hold-control-break-value Do Control Break Process Process Detail Record Read next input record Process Detail Record Add to hold fields and accumulators Move fields to output fields Write Detail Record Control Break Process Move hold control break values to output fields Write Control Break Record Zero out control break hold areas Move Current control-break-value to hold-control-break-value End-of-Program Process Do final control break Do final output report processing
31	COBOL Program to do Control Break – DATA DIVISION Areas – 1 of 3 Here's a completed example of a Control Break program. Note the following: Input record with two new fields for control break values (we will use only StateCode for this first part of the unit) The Control Break report line Hold areas for the Control Break interim-values The Control Break "hold keys" – that will be used to as comparison values with each new record read, to determine if there has been a "control break" in the file
32	COBOL Program to do Control Break – Procedure Division – 2 of 3 Driver Logic (from our pseudo-code) Process All Records – which includes PERFORM statements to paragraphs on the next slide Control Break Process – note the detailed logic in the comments
33	COBOL Program to do Control Break – Final Paragraphs – 3 of 3 Process Detail Records – note the additional code to add to the Control Break hold areas Initial Process paragraph – to setup the report, do the priming file read, and initialize the control break values End-of-Program Process – which does the final control break, and writes out the standard end-of-job report summary lines
34	:Workshop – Control Break Reports – 1 of 4 From the slide notes, copy all of the new data records – that contain the State code, and paste them into c:\customerIn.dat – replacing the existing records View the state values in the file – note that they are sorted from low to high (from California to Hawaii).
35	:Workshop – Control Break Reports – 2 of 4 From the slide notes, copy the program source (all of the COBOL statements) Create a new file in the chapter4 project, in the 1cobol folder, named: rpt2.cbl Paste the code in the editor Do a Local Syntax check of the program – ensure no errors Right-click over rpt2, and Nominate as Entry Point Rebuild the chapter4 project Expand the BuildOutput folder, right-click and select Debug As > Debug Configurations Setup a new Debug Configuration as shownè Debug the program Step to understand the code flow Resume (run) to end of program Look at the output file produced è (probably: c:\customerOut.dat) Unless you've changed the file Return to z/OS Project Perspective
36	:Workshop – Control Break Reports – 3 of 4 – Development Specs Â Let's throw in some new specs for a brand new control break program that produces a listing of employee salaries by state. Using the data in the Slide Notes, create: c:\employee.dat. (see screen capture) Note – these are well-paid employees. Probably hedge fund managers. It will line up the with the EMPLOYEE-RECORD layout shown below Using the Control Break pattern from rpt3.cbl – create a program in the chapter4 1cobol folder that produces the Control Break report shown on the next slide è There are no edit errors in this file, so you can just concentrate on coding the Control Break logic pattern
37	:Workshop – Control Break Reports – 4 of 4 – Development Specs < The employee salary Control Break Report è Optional workshop functionality includes: A report header With the current date And page# And edit routine for: Valid numeric salary A more realistic salary range for employees (who are not hedge fund managers)
38	What About Multi-Level Control Break Reports? As common as single-level control break functionality in COBOL business applications are multi-level control break reports, that have: Major key Middle key Minor key Or more levels of control break, and that process data in files that is sorted on the same key sequence. Consider this example of a (fictitious) grocery store report Note keys of: State, City, Store# And coincidentally, note that additional data control breaks would be possible (probable?) along the lines of Store Department and SKU At the risk of repeating ourselves, control break processing turns data into information
39	Data For a Two-Level Control Break Report If you're going to break on two control fields, you need to columns of data, both sorted, in a Parent à Child, or Master à Detail sequence: Sort on Parent key values Within the Parent key, sort on Child key values Note the following – in our current customerIn.dat file: Master/Parent Key data: State code Detail/Child Key data: Territory code Find both sets of values in this screen capture è
40	A Two-Level Control Break Report Note the following: Detail/Child control break lineè Master/Parent control break line è Let's have a look at the actual COBOL code used to produce this.
41	COBOL Code For a Two-Level Control Break – 1 of 2 We're going to reuse the rpt2.cbl program for this example. We will enhance it to add: A Control Break output line for Territory Control Breaks Hold fields for Territory values Note that we will have to rename the generically-named State fields In the PROCEDURE DIVISION we see the key logic modification Test for a Major/Parent key control break … then … Test for a Minor/Child key control break In that order
42	COBOL Code For a Two-Level Control Break – 2 of 2 We will need a new Minor/Child control break processing paragraph – that will eerily resemble the Major/Parent control break process. With a few exceptions: The Parent control break will perform the child control break Note that this could happen for any # of intermediate levels as well – following the data sort key relationships from highest to lowest sort-key What's important is that the Perform of lower-level control breaks happen BEFORE the upper-level control breaks. The Child control break will print out the Territory line – and re-initialize the counters and accumulators
43	:Workshop – A Two-Level Control Break Program Return to your single-level Control Break program. You will use the new data records for c:\employee.dat è They are in the Slide Notes Enhance the program to produce the report shown on the next slide
44	:Workshop – A Two-Level Control Break Program Note the Sub-Totals and total values.
45	COBOL Report Writing Patterns