Introduction

---

This guide is written primarily for use by those persons who will be using the MAGEC software to develop and maintain online and batch applications.

Copies of this guide should be distributed to:

This book is not intended to replace the Online Documentation but to augment it. This book will introduce the reader to the basic process used to generate batch applications. In order to demonstrate the tasks most effectively, it uses an actual new development project which the reader can do as he/she is following the tutorial instructions.

This guide is written assuming that the reader is familiar with the overall MAGEC philosophy. It presumes that you understand how the "standard set of nine" functions work and that you are familiar with the standard screen formats of MAGEC. You may wish to read through this book first to gain an initial understanding of the application development process. While doing the sample project it would also be useful for you to have some other MAGEC Programmer's Reference Guide chapters handy:

These are not required but will help you gain a more complete understanding of the MAGEC environment.

This tutorial may be used as an introductory course without requiring you to have read the other chapters listed above since brief explanations are included for all features necessary to develop and to test the sample application.

Throughout this book you will find explicit commands telling you exactly what to do to develop the sample application. You will also notice quite a bit of explanation and background information to help you to understand what is happening.

In order to allow you to "skim" over the background information the first pass through the book we have inserted "markers" pointing to the explicit commands. They look like this:

DO THIS: The commands will be inside a box like this.

You may wish to go through the tutorial actually doing the project as you read, then re-read it for more complete explanation. This technique seems to facilitate faster learning for most people.

Log On to MAGEC.

There is a special logon ID provided for the MAGEC installer. If you have not been assigned a logon ID and password, you can use it for doing these tutorials. The ID is: employee number 18, password ALEE.

DO THIS: Use the TS01 TransID to enter MAGEC, log on as usual.

You might not be the first one in your shop to do this project; therefore, you might need to delete the previous student's work before you begin. To do so:

DO THIS: Follow instructions in Appendix A of this tutorial, if necessary.

The sample report we will create in this project will access the same two Data Classes as we used for the sample online application. They are:

These are already defined to the MAGEC dictionary. For a better understanding of how to define data to the dictionary you might refer to the "Database Administration" chapter or "Data Definition" Tutorial in your MAGEC manuals.

The primary Data Class for this report will be VAC, the SIF data will be logically joined to it.

NOTE:

• In the development of the online application ("Application Developer" chapter of this Tutorials manual) you were introduced to the fully-automated Logical Join processes. Only the semi-automated Logical Join processes are supported for development of batch programs (as of this release of MAGEC), therefore, this tutorial will introduce you to the semi-automated process.

The report will list data for employees sorted in sequence by Date Hired, most recent dates first (descending sequence), and by Employee Name within Date Hired. It will show the employee's name, date hired, and vacation days earned and taken, sick days earned and taken, and comp days earned and taken. We have limited the report width so that it will easily fit on 80-column wide paper. This enables you to do the tutorial on a standard desktop computer as well as on your mainframe computer and to get identical results.

To develop a batch report program, first enter the "header" information into the dictionary.

DO THIS: Key in the command: BCHPGM 600B, press ENTER.

DO THIS: Fill in the screen as shown on facing page, press ENTER.

Please note that we are specifying the program name as the REPORT ID. You should substitute your name for PROGRAMMER NAME.

We are overriding some of the default values on the lower half of the screen:

This assumes that your printer can handle lower-case characters, if not then you should leave the default "Y" in the CHANGE lower-case to UPPER-CASE option.

When you press ENTER you will be taken to the data item (field) selection screen.

NOTE:

• The specifications on this screen are used to control many things. They control the layout of the report to be generated (spacing between fields, left margin or centering); they control the logic of the program to be generated (data to be read, vertical spacing, line width, upper-casing, etc.). If you wish to change some of these specifications after having generated your report and compiled the program, you will need to re-generate and re-compile in order to apply the new specifications. In some cases you will also need to delete the generated report layout so that you can re-generate it. Appendix E of this chapter of your Tutorials manual explains that further. You should complete this tutorial project before trying to understand Appendix E, however, since Appendix E assumes that you already are familiar with the standard procedures taught here.

The fields you select will be placed on the report with the first one being the leftmost column and subsequent fields added from left to right. You will have the chance to alter the order of fields using a "report painter" later on. MAGEC also will select the first three fields to be the sort fields. That is, they will be specified as the major, intermediate, and minor sort keys for the report. You can alter that using the report painter, as well. You can specify up to nine (9) sort fields. Each may be sorted on in either ascending or descending sequence. You may specify to take control breaks on any, all, or none of those sort fields. You can specify to force page breaks (head-of-form) either before, after or both before and after any of those control breaks.

The fields you select will be flagged. The sequence you select them in will be shown under the heading "Selected".

You could un-select an item by pressing PF4 with the cursor pointing to it, if you make an error, for instance.

You could un-select all items and start over by pressing PF10.

If you cursor-select a group item and press ENTER, a pop-up window will instruct you to press PF18 to automatically select all the elementary subordinate items or to press PF19 to select the single group item as one field. If you cursor-select a group item having its subordinate items selected and press PF4 (to un-select), a pop-up window will instruct you to press PF14 to un-select the selected elementary items subordinate to it.

You can page forward or backward through the multi-page list using the PF8 and PF7 keys, respectively.

Items which are part of the primary key for the data class are indicated as "Key". Elementary items which are components of the key field are numbered for your convenience and information. Items which describe the entire element (i.e. VAC01-ELEMENT) are flagged as "Elt".

When you are done selecting, pressing PF6 tells MAGEC to go on to the next step in the process.

DO THIS: Select the VAC01-DATE-HIRED by pointing to it with the cursor and pressing ENTER.

Notice that the selected item is flagged.

Also notice that the list is shown with a "top of list" marker to denote that you cannot page backwards from this point. There is also an "end of list" marker at the bottom of the list.

If you page forward when you are at the bottom of the list you will "wrap around" to the top of the list again.

If you needed to return to the Element Selection Screen (BCHPGM) you could just press PF3.

Pressing PF8 pages forward, pressing PF7 pages backward.

DO THIS: Press PF8 to page forward in the list.

You are now looking at the second page of the list of data items within the elements you will be accessing. Notice that the MAGEC dictionary definitions of items are very Cobol oriented. Anyone who is even casually acquainted with Cobol should have no difficulty in recognizing what they mean.

These definitions, and the Cobol PICTURE's, are for the data items (DIT's) in the VAC and SIF database files. You will have an opportunity to specify different PICTURE's for their corresponding report detail fields if you wish.

DO THIS: Select SIF01-LAST-NAME using the cursor and press the ENTER key. When a pop-up window appears, press PF19 to select this group fields as single items, rather than selecting the elementary items below them. (see note below).

DO THIS: Select SIF01-FIRST-NAME using the cursor and press the ENTER key. When a pop-up window appears, press PF19 to select this group fields as single items, rather than selecting the elementary items below them. (see note below).

NOTE:

• The two fields you are selecting are actually group items, they each have subordinate items below them. You will be presented a pop-up window instructing you to indicate whether you wish to select the group fields as single fields or to select the subordinate elementary items. If you press PF18 you will have each of the elementary items automatically selected, if you press PF19 you will select only the single group item. For this project we wish to select the group items as single fields (PF19).
  
  The figure on the opposite page (Figure 05) shows the appearance of the screen after you have cursor-selected one of the group items and pressed ENTER. The pop-up window will disappear when you press one of the PF keys it is instructing you to press.

Figure 06 on the opposite page shows the FIELD SELECTION SCREEN after the name field selections are complete.

DO THIS: Press PF7 to page back in the list.

Pressing PF7 has paged backward one screen and returned to the TOP OF LIST. We are now ready to select the remaining fields to be shown on the report.

DO THIS: Select the following fields in sequence by pointing to them with the cursor and pressing ENTER: VAC01-EARNED-VACATION VAC01-TAKEN-VACATION VAC01-EARNED-SICK-DAYS VAC01-TAKEN-SICK-DAYS VAC01-EARNED-COMP-DAYS VAC01-TAKEN-COMP-DAYS Turn to the next page in the manual.

Figure 08 on the opposite page shows the FIELD SELECTION SCREEN with the field selection task completed.

DO THIS: Press PF6 to Auto-Draw report.

This is the semi-automated Logical Join process. In the first development project, the one in which you developed an online application, you used the fully-automated process; in this project you are using the semi-automated process to develop a batch report program. The development of online applications currently supports both the semi-automated process and the fully-automated process; the development of batch programs supports only the semi-automated process as of this release of MAGEC.

MAGEC is showing you the Cobol code which it will generate to access the SIF01 element. It was able to generate this much based upon what is defined in the dictionary. There is one thing more which is needed and which MAGEC was unable to determine automatically, what to use as a key value.

It is asking you to build the key value in the field named SIF01-MASTER-KEY.

Notice that near the bottom of the screen is a display which tells you which element(s) you are now joining (reading) and which element(s) you have already read. It is important, sometimes, to know what data is available to you at the time this code will be executed.

The code you are shown, plus any code you key into it, will be stored in the dictionary as "customization code" which will be inserted into the generated program. You can access and modify this code at any time later as need arises. The various points in the generated program's logic at which you can insert code are called "insertion points". The insertion point where this logic will be inserted is named: %JOIN.

You could display the %JOIN customization online via the command:

NOTE:

• Extensive discussions about customization and insertion points can be found in the "Customization" chapter of the Tutorials manual, and in the Programmer's Reference Guide in the chapters titled "Insertion Points", "Analysis of the Generated MMP", and "Librarian".

DO THIS: Turn to the next page.

We are building a key by filling in the two component fields which make up SIF01-MASTER-KEY. They are a key prefix of zero, plus the employee number.

We are, in effect, using the employee number to join these two data classes.

DO THIS: Key in the two lines of code as shown on the facing page, press ENTER.

The code being shown is a standard call to the MAGEC I/O module. You can refer to the "Database Administration" chapter of the manual for more information about database accessing.

The logical join concept, plus the MAGEC element concept, give your programs a high degree of data independence. You programs actually process logical views of data rather than physical views.

Now that you have completed the logical join you are transferred to the "report painter" (RPTDEF) screen. This works much like the screen painter (MSKDEF) used when developing online applications.

The automatic report generator builds the report from left to right and top to bottom based on your field selection list sequence. It will use the number of columns specified on the BCHPGM screen (80) and begin a new line when a line is filled.

Figure 11, on the opposite page, shows the default results from the automatic report generator.

Our report will be easier to read if all of the numeric fields are on the same line; so move the "Earned Vacation" field down to the second text line and make it the leftmost field on that line.

DO THIS: Position the cursor to the Earned Vacation field and press PF21.

Notice that the message at the top-left corner of Figure 12 shows that the field selection for MOVE was successful, while the SERRMSG portion of the screen (bottom three-lines) displays the PF key options to continue the move process. PF21 will abort the field move and redisplay the Report Definition; PF12 will abort the field move and return to the BCHPGM screen. PF17 will process the field move based on the cursor position.

DO THIS: Move the cursor to the first column of the last text line displayed (not the bottom Ruler Line) and press PF17.

NOTE:

• To indicate where you wish to move the field, you point with the cursor and press PF17. MAGEC moves the field immeditely behind the field you are pointing to.

• There is a one-byte FILLER field generated as the first field on each line. In this example we are moving the selected field immediately behind that one-byte field.

• When your report is initially generated, MAGEC generates a FILLER behind each detail field in order to separate them from one another on the report. The size of this FILLER is determined by the number of spaces you specified you wanted between fields (2, in this case) on the BCHPGM header definition panel (Figure 01), and any needed padding to accommodate a heading which is longer than the detail field. When you move a detail field, its associated (following) FILLER is also moved with it.

In Figure 13 the field and heading for Earned Vacation have been removed from the first text line of the report and added to the left end of the second detail line, with the pre-existing fields shifted to the right to make room for the Earned Vacation field display. Also notice that the field specifications for the field just moved are displayed at the bottom of the screen to allow any needed changes to the field definition.

No changes are needed however for this move.

DO THIS: Press Enter to complete Field Move.

Now let's build captions for the second line of detail by inserting a line.

DO THIS: Position the cursor onto any field on the first detail line of the report (either heading or text) and press PF14.

NOTE:

• The PF14 key (line insert) inserts a new line immediately below the report line to which you are pointing with the cursor. The first line of detail in the report has a heading line generated immediately above it. Pointing to either the first line or its headings is equivalent; thus, pointing to either one and pressing PF14 will generate a new line below the first line of detail.

The Report Painter has inserted a new line after the first text line and shifted the other text line down one line. Also, there is a field now defined for the new line with a text value of "--NEW---" displayed to designate the new field's position. Select the new field and make it part of the caption we are building.

DO THIS: Position the cursor on the NEW field and press PF18.

Figure 16 on the opposite page shows a field added with the new line inserted.

A window appears displaying all of the specifications associated with that field. Let's review them.

DO THIS: Turn to the next page in this book.

• You can also specify a Source/Target for a FILLER. For example, you might want a comma printed after Last Name and before First Name. You could accomplish this by specifying COMMA-CHAR as the Source/Target for the FILLER. COMMA-CHAR is one of many special character constant fields included into every generated program as a convenience to you. To view the copybook which contains all of them, use the command: LBRSEE SPCLCHAR.

The new field is generated with a SOURCE/TARGET value of asterisk(*) so that the HEADING value will print as a literal. Any report display field with a SOURCE/TARGET of asterisk will display the HEADING value for the field value.

The field name is generated based on the row and column where the field is added. The field picture clause and length are also generated to agree with the HEADING. All other field specifications are generated as defaults, but may be changed by you, the user.

DO THIS: Change the PIC clause to X(00070) and enter the HEADING value as shown in Figure 17. Then, press ENTER.

If you draw the headings slightly different from the example, they may not align perfectly over the detail fields below; in that case you may wish to correct the headings you have drawn. After you press ENTER, the report image will show the effect of your changes. If you wish to change it again, just position the cursor onto the field and press PF18 (select for change), correct the data, and press ENTER. You can do this over and over until you are satisfied with the results.

The caption line you specified is now displayed above the second text line of quantities. Now add a second caption line below the line just created.

To add another line:

DO THIS: Position the cursor on the "Vacation" caption line and press PF14.

A dummy "--NEW---" field will be generated and displayed, just as before. Now we will update that dummy field so as to create a second line of headings above the vacation, sick, and comp time amounts.

DO THIS: Then position the cursor on the "--NEW---" field and Press PF18.

You have now selected the dummy field for update.

For the "--NEW--" field just generated to establish another new line:

DO THIS: Change the PIC Clause to X(00070), key in the HEADING Value as shown in Figure 19 and Press ENTER.

Figure 20 shows the Report Layout as we have defined it with the Caption lines for the second detail line.

The automatic report generator initially defaults your report to three sort fields and three levels of breaks. Experience has shown that this is probably the most common configuration. Further it assumed that the first three fields you selected on the report are the ones you wish to sort on, in that order. Here, in the report painter, you can override any of those defaults.

DO THIS: Press PF10 to view sort key definition.

Figure 21 shows the default sort keys generated.

MAGEC supports up to nine (9) sort fields, each may be either ascending or descending sequence. You can have control breaks (total lines) for any sort field(s), or for none of them.

The sort indicators above the field display show the sort direction (A=ascending, D=descending) and the sort levels (1=major, 2=intermediate, 3=minor, etc). Remember there can be up to nine levels. If there is to be a control break for each respective level, the direction indicator (A or D) will be shown in upper case. If there is not to be a control break, it will be in lower case.

DO THIS: Place the cursor on the first sort key field and press PF18.

You will notice that a Field Detail Specification area is displayed on the screen, similar to the information displayed when changing any display field.

To effect the desired change, merely overkey the specification that needs changing.

DO THIS: Turn to the next page.

In order to make the oldest date print first on the report, you must sort the hire-date in descending sequence instead of ascending sequence. Also, we don't want control breaks on this key.

DO THIS: Key in the changes as shown in Figure 23 for the "DIR" field and the "CTL BRK" field, and press ENTER.

Notice that the sort indicator above the first sort key is now lower case indicating no control breaks, and a value of "d", indicating descending sequence.

For our example report, we do not want any control breaks, except for the Grand Total break which is always generated at the end of the report. We will update each of the other sort fields such that they do not have control breaks specified.

DO THIS: Cursor select each of the remaining two sort Key fields for change (PF18), altering the CTL BRK parameter to "n" for each field.

The display will reflect your changes by displaying "a2" and "a3" where "A2" and "A3" were being displayed before the changes.

Now that the sort key specifications are as we want them, with none of the sort fields requesting for control breaks, and with the first sort key field (Hire Date) sorting in descending sequence. Let's return to the Report Display.

DO THIS: Press PF10.

Now combine the headings for the two "Name" fields in the first detail line to just "Name".

DO THIS: Cursor select the "First Name" field and Press PF18.

NOTE:

• Figure 26 shows the screen as it appears before the following changes are made. As you make each change, the display will be updated to reflect them. The intermediate displays are not shown in this tutorial since they should be obvious.

DO THIS: Change the HEADING value to spaces and press ENTER.

DO THIS: Cursor select the "Last Name" field and press PF18.

DO THIS: Change the Heading value to "Name" and press enter.

The heading for any field may be blanks (no heading) or it may be any character string. It need not be the same number of characters as the detail line display for that field, it may be shorter or longer. If you set or alter a heading to be longer than it was as originally generated you may also need to alter the size of the FILLER following that detail item for alignment. This is to prevent having the heading literal overlap the heading for the next (left-to-right) field.

You can specify multi-line headings, as well (for fields appearing on the first line of detail, only). To make a heading multi-line, simply use the semicolon character (;) as a "new line" character. For example, a heading specified as:

would appear on the report, and on the report painter display screen, as:

NOTE:

• When a Cobol ,programmer lays out a report, it is common for him/her to define FILLER fields before or after each data display field in order to provide visual separation and make the report easier to read. MAGEC's report generator is no different. The spaces between the data fields are actually FILLER's generated for separation. The size of each FILLER is a minimum of the size specified on the Batch Program Header screen (Figure 01) in the NUMBER OF SPACES BETWEEN FIELDS parameter; however, it may be larger in order to allow room for the preceding field's heading when the heading is longer than the field.

• You can cursor-select these FILLER's just as you cursor-select any other field in the report. You could, for example, point the cursor at the filler space between first and last name, press PF18 (select for change), then change the size of the FILLER to PIC X(1). That would move the first and last names closer together, which might produce a better looking report.

Now it is time to generate the program and execute it.

DO THIS: Press PF15 to exit MAGEC's online environment.

DO THIS: At the DOS prompt enter the command: EXEC MBP600B.

DO THIS: Submit the MBP600EX jobstream (it might need customization for your shop).

Your report should be in the JES or POWER queue as would be the printed output from any ordinary Cobol program.

Now you have created, generated, and executed a MAGEC Batch Report Program (MBP). The report produced when you execute the program should look approximately like the one shown in Figure 28.1, .2, and .3.

The program reads two database files, extracts data from them, constructs a sort file, sorts the records, and prints the report.

The automatic program generator can handle up to 9 levels of sort keys, control breaks, totals, counts, averages, multi-line detail, multi-line headings. It can be used to generate reports which print on complex pre-printed forms up to 256 columns wide and up to 999 lines long.

Customization of the program can be accomplished using standard Cobol and the customization methods proivided with MAGEC. Through customization, there is literally no limit to what can be done other than the limitations of Cobol itself.

If someone else at your installation has already done the sample report project in this book, you will have to delete all his work before you do the project, so that you can start fresh. You must be logged on to MAGEC to proceed with the steps below.

Appendix B --  Edit Type Codes

---

When you define your report using RPTDEF, or when you modify it after having allowed the auto-paint feature to generate it for you, you can specify to MAGEC that you desire automatic editing to be done to report fields. You do this by specifying, for each field, an edit type code.

These same edit type codes are also specified in the dictionary definitions for data items (DIT's). When you use the auto-paint feature (for online screens) or the automatic report program generation MAGEC sets the screen or report editing formats based upon the edit type codes found in the DIT definitions. You can override them in the MSKDEF or RPTDEF functions if you need to.

There are three general categories of edit types:

The Cobol copy book for a mask or the detail line definition for a report will contain appropriate Cobol edit patterns (i.e.. ZZZ.99-) based on the edit type. You might refer to the chapter "Analysis of the Generated MMP" (in the Programmer's Reference Guide) for more detail.

For numeric fields there is also a specification as to how many digits left of the decimal point and right of the decimal point are allowed.

One of the alphanumeric types is "T", that means table lookup validation. Operator entries (at online screens) will be validated by looking them up in a MAGEC lookup table. You can define lookup tables and the valid entries in those tables. Refer to the MAGEC "Database Administration" chapter for further details about lookup tables.

These are some of the most frequently used online MAGEC functions for application developers.

Appendix D --  Universal Functions

---

The following functions are part of logical application 00. They appear on the menu for every other logical application and can be done by anyone using MAGEC.

The specifications you enter on the BCHPGM screen (first screen in the batch report program development process) control how the report fields are generated. These report fields are displayed to you in a graphical format on the RPTDEF screen. RPTDEF is the "report painter" screen.

If you wish to alter some of these specifications after you have generated the report, you might need to delete the report detail fields from RPTDEF in order to re-generate them. This is true for those specifications which affect the layout of a report (spacing between fields, centering, etc.). To delete the report detail field definitions you should use the RPTDEL function, as:

This is similar to RPTDEF, in that it shows you a graphic image of your report layout  It does this, however, so you can confirm that you indeed wish to delete this report.

NOTE:

• By deleting these report detail field definitions you will also be deleting any modifications you have made to them via the RPTDEF facility. When you re-generate them they will have their original, default specifications.

Once you are shown the report layout, you will have three options available to you.

• abort this process by pressing the CLEAR key

• delete the detail field definitions by pressing ENTER

• delete everything, including the BCHPGM header information and field selections by pressing PF5.

If you press ENTER, only the report field definitions will be deleted, the header information and field selections will be retained. You could then return to the BCHPGM screen, alter some of the specifications, and re-generate the report using the changed specs. You could also alter the field selections, if you desired.

After you have deleted the detail field definitions the BCHPGM screen will automatically transfer you to the field selections screen(s). The selections you had made before will still be "remembered" so that you need not re-do them. You can alter the selections using all the standard PF key operations that you had available to you when you originally made your selections.

If your report included logical joins you will next be taken to the logical join coding screen. If you wish to re-do the join logic you can enter it here just as you did originally. If your original logical join coding does not need any changes, you can press PF10 on this screen to bypass the logical join process and proceed directly to the report painter screen, RPTDEF. If you press PF10 no modifications will be done to the logical join coding (stored as %JOIN customization) for your application. Any changes you might have made to it previously will be retained. If you press ENTER, rather than PF10, the coding on the screen (plus any lines of code you type in) will be stored as %JOIN customization replacing what was already on file.