Introduction

---

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

Copies of this guide should be distributed to:

This chapter will teach you how to do some of the most common types of Application Customization. To demonstrate the process most effectively, it uses sample projects based upon adding Customization to an existing sample application. It uses a tutorial approach. You must first have completed the development project in the "Application Developer" section of this Tutorials manual before you can do the projects in this set of tutorials.

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. We suggest that you first read the manual titled Application User's Guide if you have not already.

This manual has a tutorial format which guides you through the Customization of an actual sample application. The sample application was developed by following the tutorial in the chapter titled "Application Developer" which should be completed before this one is started.

While doing the sample projects it would also be useful for you to have the Programmer's Reference Guide handy for the following chapters:

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

Since the Customization coding is done using IBM Cobol this chapter assumes you are familiar with Cobol.

In this manual you will notice that there are many screen exhibits showing, step by step, exactly how each screen should look as you go through the exercise. You will also notice, on the page opposite each exhibit, both descriptive explanations and concise commands. The commands tell you exactly what to do to accomplish the project, the rest of the text gives you a more complete understanding of what you are doing and why, and how to get more information.

You may want to first go through this chapter following the tutorial exercise, doing the project as you go, and skimming over the background explanations. Then you might re-read the chapter more slowly and completely to get greater understanding. This approach has proven very effective for many people.

In order to help you to discern the commands from the background as readily as possible, you will notice that they are enclosed in a box.

DO THIS: Commands look like this.

For the first project we will add Customization to the Sample Vacation System to display four calculated figures on the screen:

While following this tutorial, you will use the Screen Painting function (MSKDEF) to add four new screen fields and you will enter the Cobol Customization logic to define and calculate the desired figures.

You will use the TSKLST to guide you through the process; however, as you become more familiar with MAGEC you will find that you often can bypass the TSKLST and go directly to any screen or function by entering the appropriate command on the top line of the screen. When you cursor select a task from the TSKLST screen, MAGEC simply "simulates" that you have keyed a command on the top line by actually moving the command there for you.

The Cobol Customization code you enter will be stored in the MAGEC Library (ALG file) and will be inserted into the generated program when you re-submit the MMPCREAT jobstream to regenerate and compile. You can always return to it to modify or add to it (or delete it) and then regenerate and compile again. The TSKLST and the Customization screens work exactly the same whether you are initially adding Customization or modifying it later on. MAGEC aids both new development and maintenance programming.

Begin by logging on to MAGEC.

DO THIS: Key in the command: TSKLST 600 . . . and press ENTER.

The TSKLST screen will serve now as your menu and status display for Customization, just is it did for the basic application development. The TSKLST display actually continues for several pages; the basic development tasks are all on the first page. You can just press ENTER on any page of the TSKLST display to page forward, unless you are on the last page already.

DO THIS: Press PF8 to page forward to the second page.

On the second page of the task list you will notice a screen full of Customization tasks.

If you examine the generated Cobol MMP (see MAGEC "Analysis of the Generated MMP") you will notice "Customization Insertion Points" denoted by percent-sign-markers, such as:

These indicate the places where you can have MAGEC insert your own Cobol code at the time that the MMPCREAT job is run to generate and compile the MMP. As you enter your Customization code online you indicate which Customization Insertion Point you are entering coding for by name. For a more complete explanation refer to the "Librarian" chapter.

On the TSKLST display you will notice those same markers shown to the right of each Customization task. This helps you to relate the task to the section in the MMP's logic to which it applies. The bottom of the first page of the TSKLST display shows a few such tasks, page 2 shows more.

DO THIS: Use the arrow keys to move the cursor to the line (on page 2) saying: "add items to VARIABLE-STORAGE (%VARSTOR)", press ENTER.

You will be transferred to the Customization Algorithm ADD screen for inserting coding into
VARIABLE-STORAGE in the LINKAGE SECTION.

The screen will be displayed to you (as shown on opposite page) with "proforma" coding already on it. The proforma simply shows you (approximately) what your coding should look like. It may be used to simplify your own entry since you can overkey it on the screen to make it say exactly what you wish. When you press ENTER whatever coding is on the screen will be added to the MAGEC Library. You may, of course, change it at any time.

As the proforma indicates, your coding in %VARSTOR should be Cobol data definitions which begin with a level 05 and do not use the VALUE clause (VALUE is illegal in LINKAGE SECTION).

NOTE:

• To protect reentrancy in the mainframe environments we recommend a rule that all work fields are to be placed into the LINKAGE SECTION's VARIABLE-STORAGE area rather than into WORKING-STORAGE. WORKING-STORAGE (insertion point name is %LITERAL) is to be used only for constants and literals, never for variables (fields you will MOVE TO). In some environments (such as WESTI) violating this rule will result in unpredictable results at execution time while in some environments (CICS) it will simply be less efficient. In any case, the rule does not cause any hardship on you since it is just as easy to put your code one place as the other.

• In the PC and Network environments there is no penalty for placing variables in WORKING-STORAGE. If your application is to be executed only in these environments you may find it convenient to do so. Remember, though, that if/when your program is swapped out of memory, all data in WORKING-STORAGE will revert to its initialized values. Data in VARIABLE-STORAGE is initialized to LOW-VALUES every time your program is invoked.

• If you desire to store data to be passed to another program or to the next invocation of this program (after sending the screen and reading the operator's response), you should place that data into the %DATADEF insertion point, rather than the %VARSTOR insertion point.

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

DO THIS: Overkey the proforma with the code shown on screen sample, press ENTER.

Your code will be recorded (added) to the Library and displayed back to you. The Function Code (on top line of screen) will be changed from ALGADD to ALGSEE. If you made an error you can just move the cursor down to the body of the screen and overkey with the correct code and press ENTER.

Your code may be entered in lowercase characters, MAGEC will automatically translate all lowercase characters to uppercase. You can override the uppercase translation feature by entering an asterisk (*) in column 1.

You may press the HELP key (PF1) for full instructions on how to use the Librarian online functions ( ALG... , etc.). If you press PF2 you will be displayed brief instructions on coding for the %VARSTOR insertion point.

DO THIS: Now, press PF12 (Shift-F2, on a PC) to return to the TSKLST.

NOTE:

• It is not necessary for you to use the Shift key to enter uppercase alphabetic characters on this screen. MAGEC will automatically change any lowercase alphabetic characters to uppercase for you. All the Librarian entry and update screens automatically translate to uppercase to simplify your work since Cobol, Assembler, and even JCL are all coded in uppercase only (Cobol II accepts lowercase coding as equivalent to uppercase coding).

• If you do wish to enter text in lowercase and not have it converted to uppercase, you must type an asterisk (*) in column 1 of each line which you do not want converted to uppercase.

The TSKLST (page 1) will appear.

DO THIS: Press PF8 to page forward to page 2.

The screen will look like the one shown here. Notice that the status of the %VARSTOR task now indicates "1 DONE". That means that you have added one "page" (record) of coding for %VARSTOR.

Next you must enter the PROCEDURE DIVISION coding to calculate the figures into the four work fields you have defined. For our purposes we will insert that coding into the "Logical Join" routine.

The routine named JA100-LOGICAL-JOIN is performed by the MMP after every READ of the Primary Data Class. When you did the Automatic Logical Join sequence in the basic development process (see MAGEC "Application Developer" Tutorial) MAGEC automatically generated a piece of Customization coding to be inserted into JA100-LOGICAL-JOIN. The name of the insertion point is %JOIN.

DO THIS: Press PF8 to page forward to page 3.

Notice that the TSKLST shows that there is one "page" of code on file for %JOIN already. That is what the Automatic Logical Join feature generated.

DO THIS: Position the cursor down to the %JOIN task, press ENTER.

You will be transferred to the screen showing the existing code which is on file.

The screen will be displayed to you as shown on the facing page. You are going to insert some additional Cobol coding near the top of this routine, after the first line of the coding which is displayed.

This means that you will be inserting using the PF20 key. Refer to the MAGEC "Librarian" chapter for full instructions or press PF1 for HELP.

DO THIS: Place the cursor on the first line of code, press PF20 (Shift F10 on PC).

This will "open up" the screen by temporarily "shoving down" all the lines of code below where you placed the cursor to allow you to key new code into the screen.

NOTE:

• The "IF (NOT-FOUND)" coding on the first line of the screen tests whether the Primary data (VAC) was successfully read. If it was not, then we do not want to try to do computations using fields from it, nor would we want to try to read the SIF data.

• If the VAC record was not found, then this routine will simply bypass its processing and effectively "do nothing". The mainline logic of the generated MMP will not attempt to use any of the data from the records because it too tests for the NOT-FOUND condition.

The MAGEC Online Librarian permits you to use the semicolon ( ; ) as a TAB character. On the ruler line you will notice semicolons showing where the TAB positions are set. You could just key semicolons on the ruler line, overriding the ones that are shown, to alter the TAB position to suit yourself. There is no need to do that now, though.

DO THIS: Key in the coding exactly as shown and press ENTER.

The semicolons will cause your coding to be aligned to the pre-set TAB positions (columns 12, 16, etc.). It is not necessary for you to use the TAB's; you could just space over to the desired column. TAB's make entering Cobol coding a little easier, though.

Notice that the display now shows your new Cobol coding inserted into the old code, just like you intended it to be. When you inserted your new code, MAGEC had to add another "page" to the %JOIN member since there are now more lines of code than can fit onto one "page". Each "page" holds 15 lines, one screenful. If you wish to see the rest of the Cobol code you can press PF8 to page forward.

DO THIS: Press PF12 (Shift-F2, on a PC) now to return to the TSKLST.

Next you must return to the "manual" Screen Painting function to add four new screen fields to Mask 600. The four new fields are to display the four calculated figures.

DO THIS: Position the cursor down to PAINT SCREEN, and press ENTER.

You will be immediately transferred to the MSKDEF screen.

Mask 600 will be displayed. On the MSKDEF screen you can make any changes or additions that you wish. You can modify or delete existing screen fields or you can add new ones by simply drawing them just as you want them to look.

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

You can use the symbols < and > to show where each new field starts and ends respectively. If one field immediately follows another then you do not need to "stop" the first one since MAGEC knows that they are not allowed to overlap and it assumes that the first one ends before the following one starts.

When you draw the fields, you can just key in the actual literal value you wish them to contain (for screen headings and constants). If you draw them with all X's or all 9's then MAGEC assumes that they are to be "variable" (enterable, unprotected) fields and changes the X's or 9's to underscores as well as setting appropriate Attributes, etc. If you draw the field using a literal value (such as Due, in the example), MAGEC assumes that the field is a constant (non-enterable, protected), rather than a variable.

There are many more things you can do on MSKDEF. For full instructions you can press the HELP key (PF1).

DO THIS: Draw the 8 new screen fields exactly as shown on the opposite page. Each variable field consists of thirteen 9's. Then press ENTER.

You could draw the new fields one at a time or all at once. There are eight (8) new fields, four constants and four variables. We will want to make these variables display-only, so we will need to modify the Attribute from what MSKDEF defaulted to. We also need to specify the database source/target names for these variables. They will be the work fields we defined earlier in %VARSTOR.

NOTE:

• You might say that we have created "virtual database fields" in this exercise since we have defined four work fields and, in %JOIN, we computed into them. The program logic can now treat them as if they were actually part of the input data.

• In the basic application development process we let the Automatic Logical Join feature "logically join" the SIF01 Element from the SIF Data Class to the data from the Primary Data Class (VAC). Now you have logically joined some virtual database fields to it.

• The result is a "Logical Record" made up of data from the VAC and SIF Data Classes (two files) and some work fields. The MMP will use the Logical Record as if it were one large record read from one file. You could easily have joined many more Elements of data from other Data Classes which might even use other access methods. Your MMP's are very highly isolated from the physical attributes of your database.

NOTE:

• If your browser is displaying a space after each less-than symbol above, ignore it--there is no space!

Notice that MSKDEF recognized the newly drawn fields and added the definitions for them to the Dictionary. It also re-drew the Mask to show you how it now looks.

The "Attribute positions" for the new fields have been altered from the < symbol which you keyed to either the d was a constant then the iel le then the | symbol appears. The | symbol indicates that this is a "virgin variable", one which has been added but whose field characteristics have not yet been updated.

The default field characteristics which MAGEC sets for screen constants are almost always 100% correct and need no modification. You can, of course, modify them if you like.

The default characteristics MAGEC sets for new screen variables often need to be reviewed and modified or added to by you. That is why the virgin variables are brought to your attention by the | symbol and the cursor "homes" to them. Notice the cursor position.

The "homing" cursor makes it easy for you to select the new variables to change their characteristics.

DO THIS: With cursor on first new variable, press PF18.

You have selected the first variable for change.

The pop-up windoiw now shows the field characteristics for the selected field. You can overkey any of them to change them. You can even change the ROW and COLumn to move the screen field.

DO THIS: Notice the pop-up window -- turn to next page in this book.

You will now change the specifications for the first variable to:

DO THIS: Key the specifications as shown, press ENTER.

NOTE:

• If you are using MAGEC in a GUI (Graphical User Interface) environment, the pop-up windows can be dragged (using the mouse) to anywhere on the screen. In a character (text) environment, the pop-up window appears in a fixed position and cannot be moved using a mouse.

Notice that you specified a Cobol screen field name of: SVACDUE and the SOURCE/TARGET field is VACATION-DUE. If you had not given any screen field name then MAGEC would generate a unique name for that field using the ROW and COLumn numbers (for example: S10-037). If you do not intend to see the Cobol compiler listing then you may not mind the "ugly" generated name. If you expect to sometimes look at the listing then you will likely prefer to give your own symbolic names to screen fields. In this exercise we will always give our own names to the variable fields. The screen constants need no names since the MMP never will reference them.

For consistency we will use the following names:

Notice that the Attribute position for the screen variable you just modified now appears as @. The cursor is positioned at the next new variable to prompt you to select it and update its characteristics.

DO THIS: Select and update the other three screen variables using the appropriate screen field names and source/target names. The attributes for each are the same as for the field SVACDUE. Press PF18 for the next field, update it and, repeat for remaining two variables.

NOTE:

• In order to acquaint you with some of the details about updating the screen field characteristics we had you do this the "hard way". Instead of just drawing: <9999999999999> and then having to modify so many field characteristics you could have used a Cobol-like edit pattern, such as: Z,ZZZ,ZZZ.99- and MAGEC would have interpreted it and set the Edit-type, Significant Digits, and Decimal Places correctly for you. You would still need to specify the Source/Target and the screen field name (optional).

• You could also have saved even more work by drawing and entering specifications for only the first variable field (SVACDUE), then using the field duplicate key (PF20) to copy it 3 times, making the appropriate changes to the specifications as you do the duplication.

You have now completed all the Customization for this project. All that remains is to regenerate Mask 600, and regenerate and compile MMP600.

DO THIS: Press PF10 to invoke the online MSKCRE function.

DO THIS: Press PF15 to exit MAGEC. Submit the MMPCREAT job and check that it ran without errors and that your MMP link-edited successfully.

DO THIS: If you are using a mainframe computer, issue the appropriate New Copy command for your environment.

DO THIS: Use the TS01 TransID to get back into MAGEC, so you can test your newly Customized application.

DO THIS: Enter: VACSEE 01 . . . and commence testing the new program.

NOTE:

• The changes you have made so far affected only the Inquiry/Maintenance functions (SEE, CHG, etc.). The Browse screens (LOC, SCN, FND) should still appear and work exactly as they did before. In the next project we will alter the Browses.

• The data displayed on your new screen comes from the VAC Data Class, the SIF Data Class, and from the new work fields you have defined.

You have just completed a non-trivial project to Customize an existing application. By now you should start feeling much more comfortable with MAGEC. You are beginning to see how you can produce any online application, regardless of how complex it is, using the standard development processes of MAGEC. You should also begin to realize just how quickly you can accomplish both new development and maintenance projects.

The speed and ease-of-use are very important when you are doing projects in a prototyping mode.

In this first Customization project we used the TSKLST heavily to guide our every step. That is appropriate when you are first introduced to MAGEC. As you become more proficient you will use the TSKLST more sparingly since you can go directly to almost any screen in the system by entering the proper commands on the top line of your screen.

In the following projects you will follow a similar tutorial to do more advanced Customization projects. We will have you, more and more, using direct commands instead of the TSKLST to get to the desired online functions. Each project must be done in order since they are designed to build upon one another to produce a rather powerful Vacation system.

For the second project, we will make a modification to the Browse screens for our Vacation system. The Browse screens can be seen by entering the VACLOC, VACSCN, or VACFND functions.

At this point the Browse display is showing five Data Items:

These were the five Items which were chosen by the Automatic Screen Painting facility. They were the first items you selected for the Mask.

Now that you have (in Sample Project 1) added a few new items to the Mask, it might be possible to improve upon the usability of the Browses by replacing the Earned Vacation display with a display of the Total Days Due (the grand total figure you calculated).

In the original application development (see MAGEC "Application Developer" Tutorial) and in Project 1 in this manual, you used the TSKLST extensively as a Developer's Menu to guide you through the processes. In this one, you will bypass TSKLST and key the appropriate commands directly into the top line of your screen, to get to any desired function immediately. This will demonstrate how MAGEC provides ease-of-use for both new users and the seasoned veterans (you are gradually becoming the latter).

Before you begin altering the Browse Display you should take one last look at it as it is.

DO THIS: Key: VACLOC 1 . . . on the top line and press ENTER.

Notice the five Data Items displayed and their Locate Headings (column headings). Notice that two of the Data Items come from the SIF Data Class (First Name and Last Name) while the rest come from the VAC Data Class. The Logical Join technique we have employed lets your program access any items from its set of data (its Logical Record) just as if they were all one large record, regardless of how many files they actually come from.

You are looking at "page 1" of the Browse. If there were more Employees on the file than would fit on one screen, you could press PF8 to "page forward". The message in SCOMPL (top right corner) will always tell you whether you have reached the END OF LIST or whether you may press PF8 to continue. If you want to restart at the beginning, you could press the PF5 key, no matter what page of the Browse you were on at the time. The record count line at the bottom of the list of Employee data shows what page you are on and how many Employees you have been shown so far.

In the lower left corner you see the message telling you that you are Browsing Forward (in ascending order). You could use the PF7 key to reverse that direction if you wished.

Near the lower left corner you see that the key being used to read the VAC data is "Employee # (9-digits)". That happens to be the only key for the VAC Data Class. If there were others you could browse using any of them and in either direction. You tell the Browses which key to use in your command on the top line, as:

MAGEC automatically supports up to nine keys per Data Class this way. If you key the command VACLOC 2 you will get an error message, since there is no key 2 defined for VAC at this time.

You may wish to refer to the MAGEC "Database Administration" chapter to learn more about defining keys, or to the MAGEC Application User's Guide for more about using the Browses.

Now you are going to alter the specifications in the Dictionary to remove the Earned Vacation from the Browse display.

DO THIS: Key: MSKDEF 600 . . . on the top line, press ENTER.

The familiar MSKDEF screen will appear showing Mask 600 as it is currently defined. You can move the cursor using the four arrow keys. You indicate the field you wish to act upon by placing the cursor on it and pressing a PF key to indicate the desired action.

DO THIS: Position the cursor to the variable field where Earned Vacation is displayed (not the prompt, the variable) and press PF18.

The indicated field's characteristics will appear in the pop-up window.

The last characteristic displayed, in the bottom line of the pop-up window is LOC. This is the Locate Position. The Earned Vacation is the fifth Data Item (left to right) on the Browse screen.

DO THIS: Alter the Locate Position from "5" to "0", press ENTER.

The change will be recorded on the Dictionary and Mask 600 will be redisplayed to you ready for further action.

Next we will add the Total Days Due variable field to our browse display.

DO THIS: Cursor select the Total Days Due variable, press PF18.

The bottom three rows now show the characteristics for the Total Days Due variable. The Locate Position is a "0". That means that this field does not appear on the Browse screens. You are going to change that.

DO THIS: Key: "5" into the Locate Position, press ENTER.

Your change will be recorded and Mask 600 will be redisplayed.

NOTE:

• At this point you have done all that is necessary to accomplish this project. All that is left is to regenerate and compile the MMP and, of course, test. You have removed one field from the Browse and you have added another. Please remember the way the Browse screen looked at the start of this exercise. Remember those Locate Headings?

• If you do nothing more now, MAGEC will generate a default Locate Heading for this new field on the Browse screen. The default name that it generates will be the Cobol source/target field name. That may be OK, but it is not the most decorative possible heading. Therefore, you will next specify the Locate Heading you wish MAGEC to use instead of generating a default.

First you should obtain a "menu" list of the screen fields from Mask 600 which are to appear on the Browse. There is a handy online function to do just that for you. It is called Screen Detail List (SCDLST).

DO THIS: Key the command: SCDLST 600 . . . on the top line, press ENTER.

Reviewing the list will show that you have indeed removed the field which we no longer want on the browses and replaced it with the new one which we do want. Notice that the first four items show that they already have a Locate Heading specified, you could change them if you needed to. Right now you have no need to change them, though. Notice that your new field has no Locate Heading specified. If you did not specify one then MAGEC would default to the source/target Cobol name.

DO THIS: Move the cursor down to the line on which the new field (STOTDUE) is shown and press PF4.

You have cursor-selected it to change it. The update screen for STOTDUE will immediately appear.

The cursor will automatically home to the only unprotected data field on this screen, "Locate Heading". You can enter any literal up to 25 characters. You may use any characters except the apostrophe because the apostrophe has special meaning to Cobol in literals.

DO THIS: Key the literal shown on the exhibit and press ENTER.

The update will be recorded. If you miskeyed you could just overkey with corrected data and press ENTER again.

Now, let's go regenerate and compile. There is no need to regenerate the Mask, but it would not hurt anything to do so. We will not need the MSKCREAT job this time, just MMPCREAT.

NOTE:

• Your terminal may be "hard-wired" to transform any lowercase alpha characters to uppercase. If so, the appearance of your screens may be slightly different from the exhibits in this chapter. There is nothing to be concerned about, this is normal.

• Notice that the identifying key in the Dictionary for your screen field's definition is made up or the Mask#, Row, and Column -- not the screen field's Cobol name (see top line of screen exhibit).

DO THIS: Press PF15 to exit MAGEC.

DO THIS: Submit MMPCREAT for Mask 600.

DO THIS: If you are using a mainframe, use the New Copy command appropriate in your environment.

DO THIS: Use the TransID TS01 to get back into MAGEC to test your modified Browses.

DO THIS: Key the command: VACLOC 1 . . . on top line and press ENTER.

Your new Browse screen now shows the Total Days Due, a computed figure, in place of the Earned Vacation. This also means that your users can do Scans and Finds (VACSCN & VACFND) on Days Due now.

You have completed this entire project without using the TSKLST once. In real life projects you would probably strike a happy medium between always and never using it. It is always there if you want it.

So far in these exercises we have worked entirely within the nine standard MAGEC functions: VACADD, VACCHG, VACLOC, etc. Next you will see how easy it is to add additional functions of your own.

First, though, let's take a look at how Customization works in MAGEC. We will see exactly what MAGEC does to insert your Custom Code into the generated MMP at the predefined Insertion Points.

When you enter Cobol Customization coding into the MAGEC screens provided for that purpose (ALGADD, CHG, etc.) that Cobol code is saved on the MAGEC Library file, the ALG file. As you have already seen, the name you use in the key actually indicates which Customization insertion point your coding is to be used for. For instance:

would add coding to be inserted at the %EDIT insertion point in the MMP. The %EDIT insertion point happens to be in the paragraph BB500-SCREEN-EDIT which is performed before any database updating occurs for ADD, CHG, or DUP functions.

The coding you enter is called "Custom Code".

When MAGEC's MMPCREAT job is generating your MMP it senses each of the insertion points by the percent markers (such as %EDIT) and then it looks on the Library (ALG file) to see if there is some code to be inserted there. It checks:

There is Default Code on file for all of the insertion points in MAGEC version 2.2 and later (Default Code is on file for some, not all, insertion points in previous releases). This Default Code is installed with the MAGEC system and is a part of MAGEC, you cannot modify it.

The Default Code is what we, the authors of MAGEC, determined to be the most likely thing that you will need at that point. For instance, the insertion point named %REDKY has the Default Code to call the I/O module (MAGECIO) to read the Primary Data Class' Elements. Most of the time the Default Code will be exactly what you need. On some projects you might need to override this Default Code, though, with your own Custom Code. Just entering Custom Coding for %REDKY will accomplish that; your Custom Code will be inserted instead of the Default Code.

NOTE: There will normally be default code in the library for every insertion point. Sometimes it will be a one-line comment--other times it will be more extensive Cobol coding.

In order to assist you in keying in your Custom Code MAGEC provides a "Proforma" on the screen whenever you do the ALGADD function. A Proforma is simply an example of what your coding might look like for that particular insertion point. The Proforma for any given insertion point would, of course, be different from the Proforma for another. There is a Proforma for every insertion point. It is only seen when you do the ALGADD function to add new Custom code.

When you use the ALGADD function, MAGEC presents a screen ready for you to key your Cobol code into. Instead of just presenting a "blank" screen, however, it presents a screen on which the appropriate Proforma is shown. In some cases the Proforma could be used as a fill-in-the-blanks coding aid; you could just overkey what you wish to be different from what is shown and leave the rest alone. When you press ENTER to let ALGADD actually add the code, it will take whatever is on the screen at that time. You can always update it again, of course.

The figure on the opposite page shows how the screen would be presented to you if you were
adding Customization for %EDIT. When you are coding Custom editing to be done in the BB500-SCREEN-EDIT routine there are certain conventions you should follow:

Since you will almost always want to follow that convention, we have established a Proforma for %EDIT which will minimize the keystrokes you need to do. You can just overkey the displayed code (especially where the dashes are shown). You could still overkey the entire Proforma with your own completely different code it you wished, but most of the time the Proforma will reduce your work and keying errors.

Proforma code exists solely to help you when keying in your Custom coding. It is merely something that MAGEC (ALGADD) places on the screen to save you as many keystrokes as possible. It does not come from the Library, it is placed on the screen for you from the ALGADD program.

Many users find that the easiest and most flexible way to use the Proforma is as follows:

NOTE:

• For most of the coding you will do in %EDIT you will simply have to overkey the dashed areas (---) and press ENTER. For the rare exceptions you can overkey the entire screen with any other coding you desire. It is perfectly okay to use the ERASE EOF key on your keyboard to delete lines. Blank lines will be "squeezed out" automatically.

• This Proforma shows an example of the coding for both a fatal error and a warning-level error. You choose the one appropriate for your edit and erase the other using the ERASE-EOF key.

In the case of the %REDKY insertion point, and many others, your Custom Code will usually be very similar to the Default Code with only minor changes or additions. For that reason you will notice that the Proforma looks just like the Default Code; you can simply overkey any changes or insert any additions. This saves you from having to rekey the entire Default routine with only a few changes. You can, if you need to, overkey the entire Proforma and thus replace the Default Code with an entirely different routine. This will be necessary only very rarely, maybe never.

You will find that the technique of first pressing ENTER to add the Proforma code to the Library and then overkeying, inserting, and deleting lines to modify it is especially useful here. When you press ENTER to initially add the code to the Library you will notice the function code on the top line of your screen change from ALGADD to ALGSEE. The PF keys to insert lines, etc, do not work in the
ALGADD function, they do work in the ALGNXT, ALGSEE, and ALGCHG functions.

If you look at the Cobol listing of the MMP before Customization was done for the %REDKY insertion point you would see the Default code that MAGEC inserted there. If you were to compare that Default code to the Proforma for %REDKY you would notice that they are nearly identical. That is because you usually need to deviate only slightly from the Default logic here, perhaps to insert a few lines of code just before or just after the CALL to MAGECIO. If there were no Proforma on the screen then you would have to key in the whole routine yourself.

Remember, the Proforma is only presented when you are doing the ALGADD function, not when you are doing ALGNXT or ALGCHG, etc. Once you have added code to the Library using
ALGADD you can then modify, add to, or delete it without restrictions.

NOTE:

• In order to assist you to discern which portions of the proforma are duplicates of the default code, MAGEC displays those portions in all uppercase. In many cases you will notice that some lines are in uppercase with some lines in lowercase. The lowercase lines are merely suggested code to show you what might be done here.

• You have the ability to overkey, or delete, any lines of the proforma, whether they are shown in uppercase or lowercase. This is just to help you to see the default coding you are customizing.

Whenever you are doing the ALGADD function MAGEC presents a Proforma on the screen to help minimize your keystrokes (and opportunities for errors). The choice of which Proforma to present is based upon the insertion point (EDIT, REDKY, etc.) you are adding code for. In most cases the Proforma initially presented will be appropriate for what you are trying to do. However, in some cases, it might not be. If you believe that there might be a more useful Proforma than the one on the screen, you can press PF4 to request a menu (list) of "Named Proformas" to choose from.

This PF4 facility is available only for the ALGADD function. When you use it you will be presented a screenful of choices. Named Proformas are identified by an 8-character member name plus an 8-character modifier, much like ordinary library members (refer to the "Librarian" chapter). You can select one by positioning the cursor on it and pressing ENTER; it will then be displayed on your screen in lieu of the one which was previously being displayed. You can modify it by overkeying, if you like, and press ENTER to add it to the dictionary as
customization code to be inserted into the program.

When MAGEC is installed, it includes a set of Named Proformas which most users find to be helpful. These include such things as SQL, IMS/DLI, and other database access calls. You are free to use these in any applications where appropriate. You can also modify or delete them, or add your own Named Proformas via the online and/or batch facilities provided.

The online functions used to do this are:

The key in all cases consists of the 8-character member name (mmmmmmmm) followed by the 8-character modifier (nnnnnnnn). In the PROLOC function the key may be incomplete or just "1". Named Proformas are very similar to any other library member except that they are limited in size to one screenful, 15 lines, of code. You can make up names for them which help the developer identify what they do. For example, if you were adding a Named Profroma to call your "home grown" rate calculation subroutine, you might name it "RATE/CALC". You would add it to the dictionary using the command:

If you use the -MAGECPUN PRO with the member and modifier names omitted then the program will punch out all the Named Proformas with separator control cards between them. The separators are actually -MAGECREP control cards so that the output can be turned around and used as input to MAGECLBR to recatalogue the members. This facilitates exporting them to another text editor, modifying them, and importing the results back to the MAGEC dictionary.

In all the examples we have used so far the key structure for the Customization Algorithms has only contained two components. For example:

Actually there are four (4) components to the key. The other two assume default values, if we do not specify them, such as:

The Modifier (8-character) is optional and will default to spaces if you do not enter it. The Page number (3-digit) is also optional and will default to zeros if you do not enter it.

When MMPCREAT is inserting your Custom coding, it seeks all the records from the Library having a key in which the Mask number and the Insertion Point name match the Mask number and Insertion Point being processed. MMPCREAT considers the Modifier and Page numbers as comments and does not look at them. Therefore, if you have several "pieces" of Custom coding on the Library, such as:

MMPCREAT will insert all three of these records' code into the Insertion Point %EDIT for Mask 600. They will be inserted in the order they are read from the Library (the order shown above). In columns 73 - 80 in the Cobol listing you would see literals displayed telling you exactly which Customization Algorithm you are looking at.

You can have up to 1000 "pages" (records) for a given unique Insertion Point/Modifier name. Each page can contain up to 15 lines.

The Modifier names can be useful to you online when you are coding or maintaining your Customization. Instead of having one very large "lump" of code for, say %EDIT, you might prefer to have several smaller pieces which you can manipulate individually and which you can access directly by name. The choice is yours.

NOTE:

• Mask numbers must be three (3) characters, with the first character a numeric digit and the other two characters either alphabetic or numeric (i.e. 9XX).

For the third project, we will add a new function, a tenth function which this MMP will support in addition to the nine standard ones. The new function will be a variation of the Browse. It will sequentially read through all the VAC records tallying the total number of days due for Vacation, Sick, and Comp days for all employees.

This new function will not display the detail like the ordinary browse (VACLOC) does. It will only display the total-for-all-employees figures. We can expect that this function will execute a bit slower than the others since it must always start at the first employee and read all the way to the last before it can present a screen.

The MAGEC Security System controls access to each Function Code, not just to a Program. Even though our Vacation MMP (MMP600) is now going to be processing ten different functions you can still have entirely separate and different security parameters for each function if need be. Just because a particular operator might be allowed to do the VACLOC or VACSEE function does not mean that you must allow him/her to do the new function.

We will name the new function "VACTOT". We will not require the operator to enter any key value (Employee#) into SKEY after the Function Code since we know that we must always begin at the very first Employee#. We will force a key value of "000000000" in the MMP.

In this project we will be doing Cobol Customization coding into some new Insertion Points. You may wish to have the chapters, MAGEC "Analysis of the Generated MMP" and MAGEC "Insertion Points" handy. They list all the Insertion Points by their actual names (%EDIT, etc.) and direct you to the place in the generated MMP where each exists. You may also refer to "Appendix H in this chapter, which lists all the Insertion Points and briefly describes their use.

If you examine the Cobol listing for MMP600 you will notice that there is an Insertion Point named %FUNCT. You will also notice that there is Default coding inserted there. The Default coding lists all the existing nine Function Codes as valid values in "88-levels".

The first thing you must do is to add your new VACTOT Function Code to this list.

In the Proforma which you will see for %FUNCT you will notice the symbolic parameter (&PFX) throughout. When MMPCREAT generates your MMP it will replace the characters (&PFX) with the Function Code Prefix. The Function Code Prefix was specified on the Screen Header definition panel, it defaults to the name of your Primary Data Class (VAC). Thus, the functions for this application are generated as: VACADD, VACCHG, etc.

You will need to make entries in two places on the %FUNCT Proforma since every Function Code is defined once in the list of valid functions and once below to indicate what kind of function it is.

DO THIS: Enter the command: ALGADD 600/FUNCT . . . and press ENTER.

The ALGADD screen will appear with the Proforma for the Insertion Point, %FUNCT.

DO THIS: Press ENTER again.

You have added Custom code to the Library, it looks exactly like the Proforma so far. Next you will modify it.

The ALGSEE screen now shows the Custom code on file for %FUNCT.

You must alter it to correctly define the nine existing Function Codes plus your new VACTOT function. You must:

Task 2 can be done by just overkeying the coding on the screen. Task 1 requires you to use the PF20 key to insert a line, as follows:

Press PF20.

Key in your new line.

Press ENTER.

DO THIS: Modify code to look like the example on opposite page.

• Inserting a line caused the code to "overflow" to a second page. You can press PF8 to page forward if you would like to see it. When you are looking at any Custom Algorithm (as you are now) the PF8 key will page you forward and the PF7 key will page you backwards through ALL the Custom code for that Mask. You can also do Searches for any character string (specified on line 2 of screen) which will scan ALL the Custom code for that Mask.

Next you will enter a bit of Customization to "force" a key value of "000000000", regardless of what is in the Screen Key field (SKEY), for the VACTOT function.

There is an Insertion Point defined at the very start of the logic of the MMP's "Browse Mainline". It is named %LOCINIT. This is a handy place to intercept the operator's entry and take action before the MMP has done much of its standard logic. This is also the Insertion Point where you can do initialization of work fields.

HINT:

• In some of your applications you may wish to prefix the operator's entry with some constant value, such as his Client number, etc.

DO THIS: Enter the command: ALGADD 600/LOCINIT/VACTOT/1 . . . press ENTER.

Notice that we had you use a Modifier and Page number this time. There was no special reason, just for "drill".

The Proforma for %LOCINIT makes it easy for you to "zero" work fields. The name ZEERO is defined in the MMP, it is the name of a constant in Working-Storage having a value of +0.

DO THIS: Overkey the Proforma with the code shown, press ENTER.

This new code will simulate that the operator has entered:

by overlaying zeros in the Screen Key field. It also initializes four work fields to zero values. These four work fields are not yet defined. In the next step you will define them.

• The field named SKEY is the actual screen field (on the top line) where the key value is entered.

NOTE:

• When you are coding customization, you may occasionally wish to move underscores to screen fields to show the operator how large a field is available for entry. MAGEC fills screen fields with underscores automatically at certain appropriate times; however, you may want underscores filled into a screen field at some other time. MAGEC automatically changes any underscores read in from the screen into spaces. This presents a bit of a problem when you are trying to type underscores into your custom code, since they will be converted to spaces.

• To move one underscore character you can code: MOVE UNDERSCORE TO ..... there is a cosntant field defined in your Working Storage, and valued appropriately, to acommodate this.

• To move more than one, you can code: MOVE ALL '-' TO ..... where the character within the quotes is a symbolic substitute for the underscore character. The substitute character on a mainframe is the Field-Mark. The substitute character on a PC or network is the ASCII 197 character. To type this character depress the Alt key and hold it down, on the numeric key pad type 1-9-7, the release the Alt key. Refer to the Librarian section of your "Programmer's Reference manual for more about underscores.

Now you need to define the new work fields which will be used to contain the totals you will be accumulating. Earlier (in Project 1) you defined four work fields in the Variable-Storage area of the TWA. Now you will add four more. You have already added the Custom code to initialize them, in %LOCINIT. You also need to add the definition of a work area to be used to build the totals display.

DO THIS: Enter the command: ALGSEE 600/VARSTOR . . . press ENTER.

The screen will be returned to you with the Function Code changed to ALGNXT, and with the existing Custom coding for %VARSTOR displayed.

DO THIS: Key the new definitions shown on the opposite page, press ENTER.

The Logical-Join routine is already calculating the "extended" figures for the first four work fields, we did that in Project 1.

The four "ALL" fields will hold the accumulated tally of the corresponding extended figures. The group item named DISPLAY-LINE will be used to display the final totals.

In order for the "ALL" fields to contain the correct totals, we must initialize them to zero (already done). Then, after the extended figures have been computed, we must add the extended figures to their corresponding "ALL" fields. We also must bypass displaying each individual employee's VAC data, and display only the final totals.

There are strategically placed Insertion Points which make all this quite easy and straight forward.

NOTE:

• Once you have become more familiar with MAGEC's online editor facility, you will be able to reduce your work by using the duplication and copying features. For example, in this step of the tutorial project you could copy lines 01 through 04 from the pre-existing text and paste them just below, starting on line 05. (Line numbers are shown on the right margin of the screen). To copy lines you would overtype the line numbers with a "CC" to indicate the starting and ending lines to be copied, then press the PF16 key. To paste those lines you would position the cursor to the first blank line after the existing text (line 05), and press PF17. You could then modify the newly pasted lines and press ENTER to update. You could also type more lines of text below them.

• If you wished to copy only one line it is not necessary to type "CC" over any of the line numbers, you simply place the cursor onto the line to be copied and press PF16. PF16 and PF17 are the standard copy/paste keys throughout MAGEC, they work in your generated applications as well.

The %SELECT Insertion Point is provided to allow you to control what will be displayed on the browse screens. All of the browse functions (VACLOC, VACSCN, VACFND, and VACTOT) can be controlled by your Custom coding here.

DO THIS: Enter the command: ALGADD 600/SELECT/VACTOT/1 . . . press ENTER.

DO THIS: Press ENTER again to add the code from the screen to the dictionary as customization code--this puts you into "edit mode" rather than "add mode".

Coding for %SELECT is inserted just before the MMP builds the line of display data for each item (employee).

There is an indicator which you can set to tell the MMP to:

The name of it is PROCESS-INDICATOR.

You are going to enter Custom coding here to bypass displaying any items and accumulate and display the totals (if the function is VACTOT). There will be more than one page (15 lines) of coding needed. You will, therefore, add two pages of Customization for %SELECT.

DO THIS: Key in the code shown for the first page - press ENTER.

The ALGNXT screen will be returned showing your first page of coding.

Next, use ALGADD again to add page 2.

DO THIS: Alter the command to: ALGADD 600/SELECT/VACTOT/2 . . . press ENTER.

The %SELECT Proforma will reappear (not shown on opposite page) ready for you to enter more Custom coding to be inserted into the SELECT Insertion Point.

DO THIS: Overkey the Proforma exactly as shown - press ENTER.

Again, the ALGNXT screen will display your second page of Custom code. You can page forward and backward to visually scan your coding, by pressing the PF8 and PF7 keys, respectively.

NOTE:

• After you have keyed in the first page of text (as in Figure 36) you could cause MAGEC to automatically create page 2 rather than having to manually type the ALGADD command as above. To do that you would place the cursor anywhere in the body of your text, but above line 15, and press PF20. PF20 is the insert key, it causes the screen to "open up" in preparation for you to insert more text after the line your cursor was on and before the line following it. When you do that on a screen which is already full (all 15 lines used) MAGEC will automatically add another page to contain the overflow, even if you do not key any more lines into the opened up screen. Then just pressing ENTER will update the member; the last line from page 1 will be overflowed to the new page 2. Now, pressing PF8, or just ENTER again, will page forward to page 2. Since you would not be doing the ALGADD function MAGEC would not present the proforma, either.

NOTE:

• The work field named LIN-CTR is a subscript used by the standard logic when it moves the display lines into the screen. It is also tested in the mainline to determine whether the screen is full.

DO THIS: Press PF15 to exit MAGEC. Resubmit MMPCREAT. Check the listing.

DO THIS: If you are using a mainframe, use the appropriate New Copy command.

DO THIS: Use the TS01 TransID to get back into MAGEC.

In order to execute the new VACTOT function, it must first be defined to the MAGEC security system.

We will not describe the tasks of the Security Officer in this chapter since your company may wish to restrict access to the Security System's functions. To avoid delays, we have taken the liberty of predefining VACTOT to the system. Therefore, it is not necessary for you to ask the Security Officer to do it. Defining a new function can be done online in less than one minute and it takes effect immediately. Refer to the MAGEC "Security" chapter for more information.

The Security Officer uses the command:

to define your new function code.

DO THIS: Have your Security Officer define the new function to the Security System (if it is not already defined). You may do it yourself if you are authorized. Refer to the notes below.

NOTE:

• You can look at the function code definition for VACTOT by doing the

• command, if the definition already exists.

NOTE:

• If you add a new function code definition, you must do the **LOAD command to tell MAGEC to reload its in-memory images of security parameters before you can test that new function.

NOTE:

• The easiest way to add the VACTOT function code definition to the repository is to duplicate the VACLOC function code definition. To do this you would:

• 1). type the command FCDSEE VACLOC, and press ENTER

• 2). alter the command to FCDDUP VACTOT, and press ENTER

DO THIS: Enter the command: VACTOT . . . press ENTER.

Your new function will read all the employees' VAC data and tally the grand totals and display them to you.

You have now completed Sample Project 3. You should now have a good working understanding of how to use the MAGEC Customization screens and Insertion Points. Of course, there are an infinite number of other types of customization which you can do.

These projects have set you off to a good start with MAGEC. You will find that you can use MAGEC for 100% of your Online Applications development since you can do anything with MAGEC that you could do with Cobol or "C" or Assembler language (it is permissable in MAGEC to CALL other-language subroutines).

You may wish to re-read this chapter, paying closer attention to the explanations on each page, in order to reinforce your understanding. The Appendices in the back of this chapter and in the back of the chapter titled "Application Developer", will be continually helpful to you as reference material.

WARNING!

This project calls for some research and some thinking on your part. It is intended to get you started using the manuals, especially the Appendices at the end of each tutorial section, to help solve real-world problems. It also teaches you how to test for PF keys and how to chain from screen to screen programmatically.

This time we will let you figure out how to do a small project on your own. The solution is in this book, immediately following this project description. We recommend that you try to solve the problem first, then look at the solution.

There are a set of standard functions for accessing the Security Information File (SIF), just like the ones you have just created for the VAC file. We would like to have the ability to transfer to the SIFSEE screen from any VAC maintenance screen (VACSEE, VACCHG, etc.) for the same employee. In other words: if you were looking at the VACSEE screen for employee 12 you should be able to press a PF key to immediately see the SIFSEE screen for employee 12 without having to type in any command. For the sake of this project let's use PF6 to do that.

The opposite page contains some helpful hints which should make the project easier for you.

You might wish to keep in mind that the generated MMP now supports ten functions, they are categorized into two classes: maintenance functions and browse functions. In this project we are interested in providing the ability to transfer from any of the maintenance functions (VACADD, VACCHG, VACDEL, VACSEE, VACNXT, VACDUP) to the SIFSEE function. We are not trying to transfer from any of the browse screens (though that is no more difficult to do).

DO THIS: Read these instructions and the hints on the facing page. Browse through the Appendices for more help.

To accomplish the objective of Test Project 4, from the prior page, you should have added the following statement into the %PFKEYM insertion point for application 600:

The sequence of the MOVE's is not important. The MOVE QUOTE TO TWA-MSK-AID is optional, but it is a good idea.

You should have added this code by doing:

• proforma is displayed

• data is added, screen returns in "edit mode"

• screen "opens up" for lines to be inserted

• new lines inserted, screen displays them

NOTE:

• The proforma for the %PFKEYM insertion point includes the logic to test for all the standard MAGEC/SAA PF keys. It also includes the logic to test for the situation in which an operator is doing an inquiry function and attempts to modify the displayed data. The default logic issues a message asking: Did you Intend to Change Data? The operator may then alter the Function Code to xxxCHG and press ENTER to complete the update. A popular alternative is to have the program bypass the question and automatically alter the function code to xxxCHG and to process the update immediately. Neither method bypasses any security since MAGEC will verify that this operator is allowed to do the CHG function before actually accepting it. The proforma for %PFKEYM shows the default logic commented out and the alternative logic added below it. If you want to retain the default method of asking the operator ratner than automatically processing the update, you must remove the asterisks from column 7 of the default code shown and remove the alternate logic below it. Otherwise, the program will do the automatic switch to the xxCHG function.

NOTE:

• By this time we assume that you have learned something from the earlier tutorials. This project gives you less "hand-holding" and leaves you to your own devices. It does give you liberal hints and suggestions to help you along, though.

MAGEC includes some very useful and powerful features associated with editing a screen field against a table of valid values. One obvious example of how these features can be used is in the validation of a State (or Province) code as part of an address.

DO THIS: This project will also require you to think about what you have learned so far. Please read the instructions below .

The Vacation file (Data Class VAC) actually contains more data than we have been using thus far in our tutorial projects. There is an Element named VAC02 which contains the City, State, and Zip (as in a U.S. street address) for each employee on the file. It is possible that for some of the employees there is not actually valid data in these fields, but merely the default value of spaces. That will become apparent to you when you try to access that data.

The very first screen you filled in when you initially began to develop the Vacation application was the Screen Header Definition. Refer to Figure 01 in the "Application Developer" tutorial. That screen (the SHDxxx screen) includes a parameter for the Verify Option. We initially set that option to NO. The verify option tells MAGEC whether to generate special code into your MMP which will protect against bad data which is read from your files and databases. As you know, Cobol programs ordinarily will abend if they try to access non-numeric data in a numeric field. Since we are now going to access Element VAC02, which we have said may contain non-numeric Zip codes (spaces), we should turn on the verify option in order to protect ourselves.

We must also add Element VAC02 to the list of Elements to be accessed from the VAC Data Class.

DO THIS: Use the SHDCHG function to alter the Verify Option from NO to VERIFY, and to add VAC02 as Element 2 under the Element Names parameters.

Be sure you receive the message in SCOMPL, top right of the screen, which says: Data UPDATED on Database, otherwise, you probably entered something incorrectly.

DO THIS: Look at the screen shown in Figure 39. Our objective is to modify the Vacation screen to look approximately like this.

The new fields are highlighted by the shadow box. There are seven new fields. Three of them are Prompts (constants). Three of them are variables. and one of them is a "W-field" used to display the state name associated with the two-character state abbreviation code.

For this project we will have you use the manual screen painting facility, MSKDEF, which you have used before (refer to Figure 12 in this "Customization" tutorial) to add the new fields to the screen. That will help familiarize you with more of the specification parameters for screen fields.

You can draw the "constants by typing the literal values, i.e. "City", directly onto the screen exactly where you want them. Don't forget to use the less than symbol (<) and greater than symbol (>) to define the size of each field.

You can draw the "variables using either all X's or all 9's to indicate alpha-numeric or numeric fields. Only the Zip Code field is numeric, the others are alpha-numeric. The city name is 15 characters long, the state code is 2 characters long, and the zip code is 5 digits long. The "W-field" in which the state name is to be displayed should be approximately 20 characters long. Its size is not very critical since MAGEC will automatically truncate or pad the state name to make it fit into whatever size field you give it.

DO THIS: Use the MSKDEF function to draw the seven new screen fields onto Mask 600.

Once you have drawn the new fields onto the screen you must modify the specifications for all but the three constant fields. To do this you use the PF18 key, as before. Each of the specification parameters will be shown with its default value, you overtype the default to alter it to the value you desire. The desired values are:

In addition, you must specify the W-Fld parameter for SSTATE as being "SSTNAM". This tells MAGEC that SSTNAM is the W-field for SSTATE. MAGEC will automatically place the description (in this case, the state name) into the W-field based upon the code (in this case, state abbreviation) entered into the T-field (in this case, SSTATE).

Also, you must specify the number of significant digits (SIG) left of the decimal point, and the number of decimal places (DEC), for any numeric fields. For the SZIP field there are 5 digits left, and no digits right of the decimal point.

We have arbitrarily specified that each of the variables will be a Required field. That means that MAGEC will issue an error message to the operator if it is left blank when doing add or change operations. If a field is optional, MAGEC will appropriately default it to either spaces or zeros on the database if it is left blank.

You should us an unprotect field attribute for the city name, state code, and zip code variables; use skip-protect attributes for the other four fields.

DO THIS: Do the MSKCRE function by pressing PF10 from the MSKDEF screen, then re-submit MMPCREAT to re-generate and compile the application.

Once you have achieved a clean compile, which should be in the first try unless you made an error somewhere along the line, you are ready to test. In the PC environment it is not necessary to issue any NEW COPY command, but on a mainframe, it is. For more detail reagrding this, refer to the discussion in the "Application Developer" tutorial regarding "New Copy of MMP" which is near Figure 15 in that section.

DO THIS: Do a NEW COPY, as appropriate

You should now be able to use the VACCHG function to try to update an employee's vacation data. The new city, state, and zip fields should be on the screen. If the data is missing (i.e. blanks) you should receive error messages, such as:

You can type into the city, state, and zip fields to update the data on file, thereby correcting the errors noted.

If you enter a valid state or province abbreviation (that is, one which is defined in Table #003), the appropriate state name will appear on the screen in the W-field. If you enter an invalid abbreviation, you will receive an error message, as:

If you point the cursor into the State Code field (SSTATE) and press PF2, the low-level Help key, you will receive field-level help for that screen field. This is much like the field-level help for any other screen field, except that there will be a message telling you that you can press PF8 to list the table of valid values (table #003, the State / Province Code Table). If you press PF8 you will receive the first page of valid state codes, subsequently pressing PF8 will page forward, PF7 pages backward.

When you have a list of state codes displayed on the screen, you can position the cursor down to the line on which the desired code appears (i.e. Texas) and press ENTER. MAGEC will then copy the code from the table into the screen field from which you pressed PF2. The screen will return to the Vacation screen, but the selected code will be filled into it automatically (i.e =. TX will be in the State Code field). This eliminates the need for your operators to memorize lists of codes.

When the code is copied from the table into your screen field, as described above, you will see a message displayed in SCOMPL saying that a code was copied from the table onto your screen. This does not update the file, it merely places the code into the screen field. You can modify it, or any other screen field's data, then press ENTER to update the record on the database.

Table #003 is provided with MAGEC when the system is initially installed. Table #003 is used for the tutorial projects and as a demonstration of how Lookup Tables work. It can also be used by any of your own applications to validate state or province codes.

Any MAGEC Lookup Table can be used by any number of applications. You can modify any Lookup Table using the built-in online functions provided with MAGEC.

Tables are identified by a 3-digit number, 001 through 999. The numbers 200 through 255 are reserved for use by the MAGEC software.

To display any given MAGEC table you can use the online command:

where nnn is the 3-digit table number.

To alter any entry in a table you can use the command:

where "nnn" is the 3-digit table number and "eeeeee" is the code (up to 16 characters long).

Similarly, you can add an entry to a table using the command:

or you can delete any entry using:

If you prefer a batch hardcopy listing of any given table, or of several tables, you can use the batch utility program, TBLLIST. Refer to the "Offline Utilities" chapter of your Programmer's Reference Guide for details regarding TBLLIST.

Now, let's look at the display of the State / Province Table.

DO THIS: Enter the command: TBLLST 003, press ENTER.

For details regarding how to define your own tables, refer to the "Database Administration" chapter of your Programmer's Reference Guide.

For details on how to produce a Where-Used report for any table, refer to the "Offline Utilities" section of your Programmer's Reference manual under the topic "MAGECLBR".

NOTE:

• In this project we will demonstrate another way that you could have added the capability for the operator to update and see the city, state, and zip code information. Rather then placing it on the VACxxx screen (MSK600), as we just did in Project 5, we could generate another program which uses a miniature screen, approximately one-fourth the size of the large full-screen display. We could have shown the city, state, and zip code data in that smaller screen and we could have "CALL"ed the small screen program from MMP600, effectively popping up a window. When the operator is finished looking at or updating the data in the small window, he/she can return to the full-screen as it was left by merely pressing PF3.

• A pop-up window program is very much like any other program except that it uses a smaller screen area and it does not erase the data previously on the screen when it is invoked. The small window is superimposed on the larger screen "behind" it. pop-up window programs can do the same kinds of functions as can full-screen programs. The standard set of nine functions is available to select from, plus any custom functions can be added.

• A pop-up window program and screen are not limited to being invoked by just one particular calling program, but rather, they can be invoked from any number of other programs. The most usual way to invoke a pop-up window program is via the MAGEC Attach / Detach facility discussed in Appendix R of this section; however, you can invoke a pop-up window program via the Fetch (discussed in Appendix B), or just by typing one of its Function Codes into SFUNCT on the screen, since they are really just ordinary programs like any other. Similarly, the Attach / Detach facility is most often used to invoke pop-up window programs, but it can also invoke full-screen programs just as well.

Since you have just finished doing a project which placed the city, state, and zip code onto the full-screen display, creating a pop-up window to display them will seem unnecessary and redundant. It is! Remember, we are doing this project just to demonstrate how to create a pop-up window application.

Developing a Pop-Up window application is really almost exactly like developing any other application. The process is very similar to the one you used in the very first project in the "Application Developer" tutorial. The differences are:

Other than that, there is really no difference from what you did in the first development tutorial project.

To invoke the pop-up window program from MMP600, you will use the Attach facility. This is very similar to what you did in Project 4, earlier in this section, except that in that project you used the Fetch facilty. The Fetch does not automatically set up for a return to the calling program and screen as the Attach does. In Cobol lingo, the Fetch and Attach are to one another as are the GO TO and PERFORM .

Since we will be developing an entirely new program, we must first choose an MMP number and Mask number for it. For this project we will choose MMP800 and Mask 800. We can use the TSKLST to help us through the process as we did before.

DO THIS: Type the command TSKLST 800, and press ENTER.

The SHDADD screen should appear with 800 set into the key area of the screen (SKEY).

DO THIS: Fill in the screen, specifying the following: (then press ENTER) MMP# 800 Function Code Prefix VAP Verify Opt VERIFY Use MODEL MODELWIN Primary DCL VAC ELTs VAC01 VAC02

NOTE:

• In this application we really want only the city, state, and zip code data (all of which are contained in element VAC02) to be displayed on the screen; however, we are selecting Element VAC01 as well as VAC02 because the key for the record is in Element VAC01. It is always advisable to read the record key with the data, even in cases where you theoretically do not need the key.

• The prefix VAP stands for Vacation Popup (an arbitrary choice). Since the function codes VACxxx have already been used, we must specify some other unique function codes for this program.

The MMPADD screen will appear with 800 filled into the key area (SKEY), and default values filled into the fields in the body of the screen. These default values were copied from the prior screen (SHDADD) and will be correct almost all of the time. There will also be a white box displayed with a message telling you that you can press PF6 to review, or modify, the selection of functions to be included into this program.

DO THIS: Press PF6.

A pop-up window appears with all nine of the standard functions highlighted (selected) as a default. You can place the cursor to the line on which any of the functions is shown and press PF4 to unselect, or ENTER to select it. We wish only to be able to see and change data in this program.

DO THIS: Unselect all functions except for SEE/NXT and CHG. Then press PF6 to apply your changes and proceed.

The TSKLST display will appear showing your current status for developing MMP800.

DO THIS: Cursor-Select the "Paint Screen" task, press ENTER.

The MSKDEF screen (manual screen painter) appears immediately. It has a square border drawn on the screen showing the dimensions of a one-fourth-size pop-up screen. The reason that MAGEC is able to know that this is a Pop Up screen, rather than a full screen, is because you specified MODELWIN in the SHD (Screen Header) definition.

NOTE:

• It is possible, and legal, for you to draw fields outside of that border, or to alter the size and shape of the pop-up screen; however, at this stage of your training it is wisest to just "color within the lines" until you have more experience and can deal with added complexity.

Since you specified to access both Element VAC01 and VAC02 earlier, you have all of the fields within both those Elements available to this application. All that is necessary to meet our objective is to place the city, state, and zip code in this screen; however, you may wish to also display the Employee number so that an operator looking at this display clearly knows to which Employee this address data belongs.

DO THIS: Draw the fields on this screen to display city, state, and zip code, with the appropriate prompts and with the W-field for displaying state name.

The fields will be exactly like those you drew in the previous project (Project 5), but they will be in different locations on the screen. Refer to the previous project if you do not remember what to do.

HINT:

• If you have spent a little time studying the Programmer's Reference manual, "Screen Painting" section, you might have noticed that you can duplicate a field from one Mask to another. You could, for example, use the Field Dup function (PF20) to duplicate a field from Mask 600 to Mask 800. You can specify the target Mask#, Row and Column when you use the Field Dup key. Doing that would reduce the amount of work you have to do here since you have already drawn fields onto Mask 600 exactly like you need them on Mask 800.

• One way to ascertain the desired Row and Column is to just move the cursor to where you would like a field and look at the bottom-right-hand corner of your screen. In most environments MAGEC, or the terminal controller, will display the Row and Column of the cursor's position there.

DO THIS: Press PF10 to execute MSKCRE.

MSKCRE will generate the screen Mask and the Cobol copybook for it.Next, MSKSEE will display the new screen to you.

At this point you have finished generating the screen Mask and it is time to generate the MMP (program).

DO THIS: Press PF15 to exit MAGEC.

DO THIS: Submit the MMPCREAT batch jobstream for 800.

If you have a clean compile, you are ready to test the new program. If not, correct your errors and re-submit MMPCREAT, then begin testing.

DO THIS: Log back onto MAGEC using the TS01 transid, Employee# 18, password=ALEE.

Since the new program is not yet being invoked by any other program, the only way for you to test it now is to type in the Function Code with an appropriate key value.

DO THIS: Type in the command: VAPSEE 01, and press ENTER

Your little pop-up screen should appear with the data for Employee 01 showing. If you wish, you can update the data by changing it on the screen and doing the VAPCHG function.

If all this seems to work, the next task will be to add the code into MMP600 to Attach to the VAPSEE function upon sensing some PF key. For this project we will use PF10 to invoke the VAPSEE pop-up.

Since the keys for the VACxxx and VAPxxx functions are identical (Employee#), it is not necessary to alter the contents of SKEY at all in order to invoke the VAPxxx functions from the VACxxx functions; therefore, we only need to alter the contents of SFUNCTand then to go do the Attach.

The insertion point at which this should be done is, you guessed it, %PFKEYM.

DO THIS: Type the command: ALGSEE 600/PFKEYM, and press ENTER.

The screen will display the PFKEYM custom coding as we last left it in Project 4 earlier. The code to sense PF6 and Fetch to SIFSEE is still there where we put it. Now we will add a test for another PF key (PF10) and an Attach to VAPSEE if PF10 was hit.

DO THIS: Place the cursor onto the ruler line, above the first line of Cobol code, and press PF20 to insert more code.

The screen "opens up" allowing you to type in more code to be inserted before the first line of Cobol code which was shown on the screen.

DO THIS: TYPE in the following Cobol code:

IF (TWA-MSK-PF10-HIT)

MOVE 'VAPSEE' TO SFUNCT

GO TO AA760-ATTACH.

DO THIS: Press ENTER.

The screen will return to you with your new lines of code inserted at the top.

DO THIS: Press PF15 to exit MAGEC.

Next you must re-compile MMP600 to include the new custom coding.

DO THIS: Submit MMPCREAT for 600.

DO THIS: Log back into MAGEC, as before.

Now we will test the Attach from the VACSEE screen to the VAPSEE pop-up, and then the Detach back to the VACSEE screen.

DO THIS: Type in the command: VACSEE 01, and press ENTER.

The familiar VACSEE screen should be displayed.

DO THIS: Press PF10.

The VAPSEE pop-up should appear supreimposed on the VACSEE screen. You may change the data and do the VAPCHG function here, if you wish.

DO THIS: Press PF3.

The VAPSEE pop-up should disappear, returning to the VACSEE screen "as it was before you pressed PF10. If you altered the city, state, zip code data in the pop-up, the altered values will not show on the VACSEE display until you press ENTER to refresh the screen.

Since your MAGEC MMP's are Cobol programs you are able to use the standard facility of your TP Monitor to invoke another program as a subtask. This is known as "linking" to another program in some circles. You can code the "native" command in your Customization coding as:

EXEC CICS LINK . . . etc. CALL 'WSTCOBOL' USING SIGNOFF, SOLINK . . . etc.

and so forth, depending on your TP Monitor.

However, there is a better way. Your MMP automatically includes a "service routine" which you can perform to accomplish the same thing a lot easier. Using the built-in service routine also keeps your MMP's portable since MAGEC will generate the appropriate code into it if you upgrade or transport to another TP Monitor.

In order to take advantage of this routine your subprogram must be named according to the MAGEC standard (MMPnnn) on the Load Library (OS) or Core Image Library (DOS).

You can use the routine to invoke a subprogram at any time in the MMP. The TWA data is passed to the subprogram and back to the calling MMP. The two programs can communicate with each other using the TWA. The TWA is not saved, initialized, or restored by MAGEC when you invoke subprograms this way. If your MMP moves a value into a field in the TWA before invoking the subprogram, then the subprogram will "see" the value in that field. If the subprogram alters that value before it returns back to your MMP, then your MMP will "see" the altered value.

To invoke a subprogram, code:

Control will return to the next sequential instruction after the PERFORM.

Often in your development you will find a need to establish a sequence of screens in your applications. For instance, you might decide that whenever an operator completes the screen function to add a new customer to the Customer file (ie. CUSADD function) the next thing that he/she will probably want to do will be to add an invoice for that customer (ie. IVCADD function). You would probably want the IVCADD screen to "pop up" automatically, ready for data to be keyed into it.

Another example might be a case where you want to give the operator the capability to hit a PF key (or to type something onto the screen) to indicate that he/she wishes to transfer immediately to some predetermined screen function. A menu-type screen would be an example of this.

MAGEC has a built-in facility to accommodate "fetching" to another screen function. To do so, just code:

The entire TWA and all Mask data is passed to the "fetched" MMP intact. You can also move a value into the Screen Key field (SKEY) to be passed to the fetched MMP. It is also permissable for the Function Code specified to be one of the functions handled by this same MMP; for instance VACLOC could legally fetch to VACSEE. Indeed, when you use the cursor-selection feature of VACLOC that is exactly what happens.

There is also a way you can fetch by specifying the MMP number instead of a Function Code. This feature exists solely to facilitate conversions from non-MAGEC applications to MAGEC. We recommend that you use the FTH-FUNCT method whenever possible.

To fetch a specific MMP you would code:

where 'mmm' is the MMP number of the program to be fetched. It must be named according to the MAGEC standards for Load Library (OS) or Core Image Library (DOS) members.

You must not GO TO AA900-GOBACK from within a PERFORM'ed routine.

NOTE:

• (This note applies to BOTH of the above types of fetches.)

• When the fetched program completes its processing it does not return back to the MMP which fetched it. The fetched MMP has logically "overlaid" your MMP and when it completes it will return to the MAGEC Control Program (just as your MMP's do). The fetched program may fetch another MMP, which may also fetch another MMP, and so on. Excessive use of this facility could have an adverse effect upon online performance.

The standard logic generated for your MMP includes all the correct coding to initialize the TWA-MSK-AREA with either the common browse Mask (Mask 652) or the Mask you generated (Mask 600) at the proper times. You will most likely never need to add Custom coding to initialize the Mask area; however, there is a facility for you to do so, in case you ever require it.

You might someday want to develop an MMP which uses more than just the two Masks which are automatically handled in the standard logic. In that case you would have to initialize the area with your other Masks at the proper times. There is no limit as to how many Masks an MMP may use.

To initialize the TWA-MSK-AREA code:

The initialization of the Mask area actually involves a read of the Mask's initialization record from the MAGEC MSK file. It is done by the I/O module (MAGECIO). The error status (GET-MSK-ERR) is set by MAGECIO if an error of any sort was encountered in trying to read the record. The BB800 routine contains the RECOMMENDED action to be taken when such an error occurs, you may want to deviate from that -- just BE CAREFUL!

When a Mask is to be read into your appplication you will almost certainly wish to include the copybook which describes that mask. A standard online MMP already used three Masks by default. They are the maintenance screen mask, the common browse mask, and the pop-up window mask for the Short-List feature. The copybooks for these are automatically included into the MMP.

If you need to include a copybook for another Mask, it should be inserted into the %USRAREA insertion point. Remember, these Mask copybooks all redefine the same area, TWA-MSK-DETAIL, and therefore you must be careful not to reference datanames for fields within one Mask while a different Mask is "active". This is true even with the standard default MMP's which use only the basic three Masks. Since the references to these standard Masks are largely generated by MAGEC, they already abide by this restriction. It is only in your customization where you are likely to cause a problem.

Sometimes you will have occasion to add Customization coding to cause your MMP to just terminate its processing and pass control to the "Logo screen". The Logo screen is also called the "Clear screen", it is the screen on which either the MAGEC logo or your company's logo is displayed. It also has a message on line 2 of the screen saying: "ENTER FUNCTION CODE".

To fetch the Clear (Logo) screen, code:

When MAGEC does its Automatic Editing for your screen fields it sets standard Error Numbers which cause the corresponding Error Messages to be displayed on the last three lines of the screen. If you do any Custom coding and add some editing of your own you should follow the same convention.

The Automatic Editing also flags which screen fields are in error, so that they will be automatically altered to "highlighted" on the screen. This means that they will appear either double brightness or in a highlight color (red) for easy identification.

To set the Error Number and flag a screen field as being in error, enter coding as follows:

In the %EDIT Insertion Point this code will cause the MMP to bypass updating the file(s) and just return to MAGECCP to have the Error Messages issued.

If you wish to flag a non-fatal (warning level) error, code:

The above code will allow the MMP's updating to occur, but will tell MAGECCP to also place the specified Error Message into the screen.

The Error Numbers and Error Messages which MAGEC places into the last three lines of the screen (SERRMSG) are defined on the ERR file. Error Numbers are 3-character, alpha-numeric codes. The "numbers" which start with "9" are reserved for MAGEC system use, you can use any other Error Numbers for your own applications.

To add a new Error Number online, enter the command:

where nnn = the 3-character Error Number you wish to add, then press ENTER.

The ERRADD screen will be presented. You must enter two things:

The 3270 terminals have (depending on the model) up to 24 PF keys which the operator can press instead of just pressing the ENTER key. The PF keys send the data to the CPU just like the ENTER key does, thus there are 25 keys the operator can use to send the screen data. The CLEAR key, the PA keys and the TEST key do not count since they do not send the screen data, just a one-byte code.

You can use the PF keys to make your application much more "user friendly" since it is obviously easier to press a PF key than to type something on the screen and press ENTER (fewer keystrokes). Some PF keys are already being used for built-in features. For instance, PF9 is used to Swap Windows, PF15 exits MAGEC, etc. The rest are available for you to use as you see fit in each application.

To test which key was used, code:

You can do this at any time in the processing logic. There is an 88-level value for every possible key.

Sometimes you may need (or want) to "fool" your program (or one that you transfer to) into "thinking" that a different key was pressed that what actually was pressed. An example of such a case is when you have two screens which allow the user to transfer back and forth using the same key (for instance PF2). Each program would test for PF2 and would, if PF2 was hit, transfer to the other. Before actually transferring, however, it should reset the indicator to something other than "PF2" in order to prevent a loop in which each program senses PF2 and transfers to the other infinitely. The most common thing to do is to set the indicator to say that ENTER was pressed, as:

MOVE QUOTE TO TWA-MSK-AID.

You can set other values to indicate other keys, as well. The TWADSC-C copybook contains a list of all possible keys and their associated values, if you are interested.

Below is a list of the Customization Insertion Points where you can enter Custom coding. Beside each is a brief description of some of the most common types of coding done there. This list is organized following the sequence found in a generated program. An alphabetical list of Insertion Points begins on page I-4.

CommentsY =

Define data and working areas

Procedural and data access

Procedural and data access (cont.)

Procedural and data access (cont.)

Alphabetical List (cont.)

Alphabetical List (cont.)

The top row of every screen in MAGEC is defined in a standard way and contains the SFUNCT, SKEY, and SCOMPL screen fields. The bottom three rows are always defined as one 240-byte field named SERRMSG. Although these areas of the screen are used by MAGEC for specific purposes there are occasions when you may wish to display data or messages in SCOMPL or SERRMSG. You may do so with the understanding that MAGEC will, under certain conditions, overlay what you have placed there with error messages or other system messages.

If you wish to display data in the last three rows of the screen you could define a work area in VARIABLE-STORAGE, move the desired literals and data fields into the work area to build your display, and then move the entire work area to the last three lines as:

The SERRMSG area is also "broken-down" into six 40-byte fields. You can, therefore, also move to the 40-byte fields individually as:

If you wish to move a message to the SCOMPL screen field on the top line of the screen you may code:

• You may only use the SERRMSG and SCOMPL areas for display-only purposes. If screen field editing errors are detected by the MAGEC Automatic Editing feature or by your customization coding then SERRMSG and SCOMPL will be cleared and error messages will be placed there, overlaying your display.

Occasionally it will be desirable to provide a "seamless" connection between a new application you have created in MAGEC an an existing application. For example, suppose that you wanted to enhance your old online Inventory system by adding browse, inquiry, and update facilities for your Vendor data. Further, suppose that you wanted the new functions to be "embedded" into a sequence of screens which already exists (and was not developed using MAGEC).

This can be done easily using the built-in facilities of MAGEC for passing control between MAGEC and non-MAGEC applications. The operator could see a sequence of screens consisting of your old non-MAGEC screen(s), followed by new MAGEC-generated screens, followed by more old screens. The operator need not log onto and off of MAGEC repeatedly in order to do this. The applications can pass data back and forth, as well.

To transfer from your MAGEC MMP to a non-MAGEC application, you have two alternatives: you can transfer to a Tran-ID or to a program name. To transfer to a Tran-ID, code:

MOVE 'TRANSFER' TO TWA-NONTP-REQUEST.
MOVE 'tttt----dd...dd' TO SERRMSG.
GO TO AA900-GOBACK.

Where: "tttt" is the desired Tran-ID (followed by four dashes), and "dd...dd" is up to 232 bytes of data to be passed. The non-MAGEC application will be invoked via a CICS "START". The four dashes signal MAGEC to use the START technique, rather than the XCTL technique (discussed below). The data area length will always be 232 when passed to the START'ed transaction - unless you specify that you do not ant to pass any data.

If you do not wish to pass any data to the Tran-ID you are transferring to, then SERRMSG should be set to 'tttt----' followed by 232 bytes of LOW-VALUES

To transfer to a program by name, code:

MOVE 'TRANSFER' TO TWA-NONTP-REQUEST.
MOVE 'ppppppppdd...dd' TO SERRMSG.
GO TO AA900-GOBACK.

Where: "pppppppp" is the desired program name, and "dd...dd" is up to 232 bytes of data to be passed. The non-MAGEC application will be invoked via a CICS "XCTL". The data will be passed to the XCTL'ed program as a 232-byte COMMAREA. The XCTL'ed program may ignore the COMMAREA if it does not need any data passed. The absence of the four dashes (see above) signals MAGEC to use the XCTL technique, rather than the START technique.

NOTE:

• MAGEC will either save the TWA to the TW3K1 file or not save it based upon the setting of XFROT-TWA-SAVE in Table 243. A setting of YES will tell it to save the TWA.

To transfer to a MAGEC application, your non-MAGEC program has two options: to use the CICS START to invoke the special Tran-ID "MAGX", or to use the CICS XCTL to invoke the program "MAGXFRIN". Either way you must pass a parameter (or COMMAREA) containing 41 bytes of data (plus optionally, up to 240 bytes of additional data) which includes:

NOTE: if the operator is not already logged onto MAGEC, the SYSLOG ON screen will automatically be presented, ignoring the function and key you have passed.

To transfer into MAGEC via the START technique, code:

EXEC CICS START
    TRANSID('MAGX')
    TERMID(WS-TERMID)
    FROM(PARMS-TO-MAGEC)
    LENGTH(41)    [thru 281]
    INTERVAL(000001)
END-EXEC.

Where: PARMS-TO-MAGEC is a 41 byte (through 281 byte) long area containing the MAGEC Tran-ID (i.e. TS01), the 6-character function code, the 31-byte key, plus (optionally) the user data to be passed to the MAGEC MMP. For example:

01  PARMS-TO-MAGEC.
    03 PTM-TRAN-ID    PIC X(04)   VALUE 'TS01'.
    03 PTM-FUNCT      PIC X(06)   VALUE 'CUSSEE'.
    03 PTM-KEY        PIC X(31)   VALUE '123'.
    03 PTM-DATA       PIC X(240)  VALUE 'data to the MMP'.

The above would transfer into MAGEC via MAGEC's User-View 'TS01' and immediately present the CUSSEE screen for customer 123 (if such exists). The MMP will receive the 240-byte passed data in the SERRMSG field in its TWA. NOTE: the receiving MMP should be sure to use or save the passed data from SERRMSG before the initialization of the TWA-MSK-DETAIL area by either the reading of a Mask or by the BA200-INIT-ATTRIBUTES routine.

To transfer into MAGEC via the XCTL technique, code:

EXEC CICS XCTL
    PROGRAM('MAGXFRIN')
    COMMAREA(PARMS-TO-MAGEC)
    LENGTH(000041)     [thru 000281]
END-EXEC.

Where PARMS-TO-MAGEC is as shown above for the START technique.

Some MAGEC users have external security systems, such as RACF, ACF2, or Top Secret, or a home-grown security system. Some would prefer that their end users not have to log onto MAGEC (via the SYSLOG ON command) since they have already logged onto the system through the external security system. This can be accommodated rather easily using the MAGLOGON program provided with MAGEC.

MAGLOGON is a sub program designed to be called (via EXEC CICS LINK) from any ordinary CICS program. It accepts input parameters via the DFHCOMMAREA and it can either log a user on or off of MAGEC. The normal mode of use would be for you to code a simple CICS program which interrogates your external security system to obtain the ID of the operator and then calls MAGLOGON to log him/her onto MAGEC. The sequence of events would be:

01 DFHCOMMAREA. 05 MAGEC-PARAMETERS. 07 MAGEC-REQUEST PIC X(03). 88 MAGEC-REQUEST-LOGON VALUE 'ON ' 'IN '. 88 MAGEC-REQUEST-LOGOFF VALUE 'OFF' 'OUT'. 88 MAGEC-REQUEST-COMPLETE VALUE SPACES. 07 MAGEC-USER-VIEW. 09 MAGEC-T-OR-P PIC X(01). 88 MAGEC-T-OR-P-VALID VALUE 'T' 'P'. 09 FILLER PIC X(02). 09 MAGEC-VIEW-NO PI C X(01). 88 MAGEC-VIEW-NO-VALID VALUE '1' THRU '8'. 07 MAGEC-USER-IDENTIFIER. 09 MAGEC-USER-EMPNUM PIC 9(09). 09 FILLER PIC X(07). 07 MAGEC-EMPLOYEE-NUMBER PIC 9(09).

When filling in the request area you must set one of the valid request commands into the MAGEC-REQUEST field. It would probably be a good practice to move your command to the group item MAGEC-PARAMETERS in order to ensure clearing the rest of the request area with spaces.

You must also specify one of the MAGEC user-views (TS01 - TS08, or PR01 - PR08) in the field named MAGEC-USER-VIEW. Then you must specify the operator's ID from the external security system in the field named MAGEC-USER-IDENTIFIER. This may be any alpha-numeric ID up to sixteen characters long.

If your logon request is successful, the MAGEC-REQUEST field will be set to spaces and the operator's employee number (from the MAGEC security system) will be returned to you in the MAGEC-EMPLOYEE-NUMBER field. This is just for your information, the operator is already logged onto MAGEC.

If the MAGEC-REQUEST field is returned to you with a value of 'COM', your logon attempt failed because of a badly formatted COMMAREA.

The MAGLOGON program translates the external ID to a MAGEC employee number via a special security ID translation table which is called "Table SSS". You can maintain Table SSS using the online functions: SSSADD, SSSCHG, et cetera.

For example:

would return you the screen to enter the MAGEC employee number for Joe Jones (assuming his external security ID is JOE JONES). Then you simply enter his employee number into the screenfield titled "MAGEC Employee Number".

Cobol programmers often utilize certain Cobol verbs which facilitate conversions or transformations of characters. This is a useful feature of Cobol, expecially when it is necessary to change lowercase alphabetics to uppercase or vice-versa, but is accompanied by some problems. The problems arise because of the differences between Cobol compilers. These differences are apparent when compilers for VSE versus MVS, or ANSI '74 versus ANSI '85 (especially IBM VS Cobol II), or ANSI '68.

MAGEC provides several "subroutines" which can be called to accomplish the functions of some of these verbs.

The Transform verb is used for converting characters in an area using corresponding tables of "from" characters and "to" characters. For example:

TRANSFORM CUS01-NAME FROM LOWER-CASE TO UPPER-CASE.

Where CUS01-NAME is the field to be operated upon, whose characters are to be converted, LOWER-CASE is a table of characters to be converted, UPPER-CASE is a table (the same length as LOWER-CASE) of characters to convert to. The identical function can be accomplished using a MAGEC-provided subroutine, as:

CALL 'MAGXFRM' USING FORTY CUS01-NAME
TWENTY-SIX LOWER-CASE UPPER-CASE.

Where: FORTY is a PIC S9(4) COMP SYNC data field having a value equal to the length (in bytes) of CUS01-NAME, and TWENTY-SIX is a similar field containing the length of (each of) the two tables. Note: for this example we assume that the length of LOWER-CASE and UPPER-CASE is 26 bytes each.

Another way to do the same thing, with slightly less coding, is:

CALL 'UPCASE' USING FORTY CUS01-NAME.

To convert from uppercase to lowercase, code:

CALL 'LOWCASE' USING FORTY CUS01-NAME.

The first subroutine, MAGXFRM, is more versatile and can be used for other conversions, while the UPCASE and LOWCASE subroutines are specifically for converting to upper- or lower-case alphabetics.

The default meanings for PF2, PF16, and PF17 are:

In most cases you will probably leave these key assignments as they default since these three keys are not usually used for other purposes in most environments. Sometimes, however, you may need to assign other key to these functions, freeing these keys for another purpose.

The assignment of these keys is done in the %PFKEYL and %PFKEYM insertion points of your online MMP's. It is done as Default coding, you can override it by entering Customization for these insertion points.

There is a copybook member named "PFKEYS/SAAMAGEC" which is included into your MMP's in the Default code for %PFKEYM. It contains the code to assign all three of these PF keys (PF2 PF16, and PF17) to their meanings described above. You could override it by:

A sample of the code which might be entered to replace it is:

***** Substitute PF23 for PF2 (field-help)
IF (TWA-MSK-PF23-HIT)
     MOVE '2' TO TWA-MSK-AID
     MOVE SFUNCT TO TWA-LAST-FUNCT
     MOVE FTH-FUNCT TO TWA-NONTP-REQUEST
     MOVE '**ERR1' TO SFUNCT
     GO TO AA900-GOBACK.

Note:

• Setting TWA-MSK-AID to '2' simulates that PF2 was hit, "fooling" the **ERR1 program into processing as if PF2 actually were pressed. You can do the same type of logic to simulate PF16 and PF17 by using the equivalent TWA-MSK-AID codes. They are:

The insertion point %PFKEYL only contains the code to test for PF16 (Copy key). It can be overriden by adding Customization for %PFKEYL and simply overkeying the code shown on the screen (similar to code shown above).

In some cases you may wish to assign an alternate PF key to have the same meaning as another. An example of this might be to make PF23 an alternate for PF13. PF13 is normally the "Hardcopy Key" in MAGEC programs, it causes the program to route its output to the MAGEC spooler for printed output instead of to the screen. You could cause PF23 to have the same effect by adding Customization coding into the insertion point %PREINIT, as:

IF (TWA-MSK-PF23-HIT)
    MOVE 'A' TO TWA-MSK-AID.

The result would be that pressing either PF13 or PF23 would produce hardcopy output.

If you wished to make PF23 produce hardcopy output and to make PF13 not produce hardcopy output, code:

IF (TWA-MSK-PF13-HIT)
    MOVE QUOTE TO TWA-MSK-AID.
IF (TWA-MSK-PF23-HIT)
    MOVE 'A' TO TWA-MSK-AID.

The above makes PF13 simulate the ENTER key and PF23 simulate PF13.

Similar assignments can be done for other keys. The codes used to set values into TWA-MSK-AID are:

Key       Value        Key       Value

ENTER     QUOTE        PF16      'D'
PF1       '1'          PF17      'E'
PF2       '2'          PF18      'F'
PF3       '3'          PF19      'G'
PF4       '4'          PF20      'H'
PF5       '5'          PF21      'I'
PF6       '6'          PF22      Cent Sign
PF7       '7'          PF23      '.'
PF8       '8'          PF24      '<'
PF15      '9'          PA1       '%'
PF10      ':'          PA2       '>'
PF11      '#'          PA3       ','
PF12      '@'          CLR       '_'
PF13      'A'        SEL PEN     '='
PF14      'B'        TST REQ     ZERO
PF15      'C'        VZN REQ     'V'


The Pattern handling facilities of MAGEC are embedded as performed routines within the generated programs. This enables you to utilize these facilities yourself through customization coding, just as they are used by MAGEC for generated pattern handling logic. You can apply a pattern to a data field to format for display, to validate (edit) a data field's contents using a pattern, or to de-patternize (remove the pattern from) a data field in order to use it to update the database or in calculations.

To apply a pattern to a data field in order to format it for display (either video or print), if it is not a numeric field, code the following (in %COMP, %LOCMOV, or other insertion points):

MOVE 'XXX-AA99/9X-A'       (or any valid pattern)

    TO PATTERN-MASK.

MOVE data-field TO DE-EDITED-DATA.

PERFORM CB200-INSERT-PATTERN THRU CB299-EXIT.

MOVE SCREEN-FIELD TO target-display-field.

if it is a numeric field, code:

MOVE '99/999-9999' (or any valid numeric pattern)

    TO PATTERN-MASK.

MOVE SPACES TO DE-EDITED-DATA.

MOVE data-field TO DE-EDITED-VALUE.

PERFORM CB200-INSERT-PATTERN THRU CB299-EXIT.

MOVE SCREEN-FIELD TO target-display-field.

To validate (edit) the format of an input data field using the Pattern editing, code (usually in %EDIT):

MOVE data-field TO SCREEN-FIELD.

MOVE 'XX-99-XXX-AA' (or any valid pattern)

    TO PATTERN-MASK.

PERFORM CB500-EDIT-PATTERN THRU CB599-EXIT.

IF PATTERN-ERROR EQUAL E

    MOVE E TO data-fieldE

    PERFORM CA100-LOAD-ERR-CODE-TBL THRU CA199-EXIT

ELSE

    MOVE SCREEN-FIELD TO data-field.

To remove the pattern insertion characters from a patternized field, code (usually in %CALC):

MOVE 'XX99-A99/X' (or any valid pattern)

    TO PATTERN-MASK.

MOVE field-with-pattern TO SCREEN-FIELD.

PERFORM CB600-STRIP-PATTERN THRU CB699-EXIT.

MOVE DE-EDITED-DATA TO data-field.

          - or --

MOVE DE-EDITED-VALUE TO data-field.

The default logic generated by MAGEC for online MMP's stipulates that the key component fields (if there is more than one component field) are separated by a slash (/). This should be a good standard in most cases, however, sometimes it is desireable to use another character. One example of such a case is when the key data is a code which might contain a slash as a valid data character (such as a part number).

To alter the delimiter character used, you must enter a single line of Cobol customization coding into the %PREINIT insertion point. That line of code should say:

MOVE '-' TO D-LIMITER.

Where '-' is any valid character which you desire to be used as the new delimiter in place of the default slash.

The MAGDATE subroutine is provided with MAGEC in order to facilitate the conversions, comparisons, and validations of dates. It accepts Gregorian, Julian, and alpha-numeric date formats as input and validates and converts to any/all formats automatically.

To use MAGDATE your program must include the MAGDATE request area. It may be included into both online and batch programs in the Working Storage area (insertion point %LITERAL). Your program must fill in the appropriate fields within the request area and then:

CALL 'MAGDATE' USING MAGEC-DATE-REQUEST-AREA.

You should always test the return code to verify whether MAGDATE has encountered an error in your request or has successfully completed the request. To test for successful completion , code:

IF (MAGDATE-OK) ...

There are condition names (88-level names) for a variety of possible error codes. You might wish to test for which type of error was found in the case that MAGDATE-OK is not true. The various return code values will be discussed later in this appendix.

The MAGDATE request area is defined in Cobol in a library include member (copybook). To include it into your Working Storage, code:

-MAGECINC DATRQ-C

The following format is an abbreviated version of the DATRQ-C copybook. The actual copybook includes several breakdowns of the various fields and lists of condition names (88-levels) for values. These may be useful to you in some cases, so you may wish to review the actual copybook to familiarize yourself with them. It is not necessary to do so in order to use the basic functions of MAGDATE, however. The copybook is coded beginiing with a Cobol 04-level item. That facilitates including it into %VARSTOR or %DATADEF, if you find a need to do so. If you are including it into %LITERAL you might wish to preceed the -MAGECINC statement with an 01-level item (i.e. 01 MAGDATE-AREA).

  04 MAGEC-DATE-REQUEST-AREA.
    05 MAGEC-DATE-REQ-RESERVED      PIC X(04).
    05 MAGEC-BIN-THRU REDEFINES MAGEC-DATE-REQ-RESERVED PIC S9(8) COMP.

    05 MAGEC-DATE-FROM      PIC X(12).

    05 FILLER  REDEFINES MAGEC-DATE-FROM.

        07 MAGEC-DATE-FROM-N                PIC 9(8).
    05 MAGEC-DATE-FORMAT      PIC X(12).


    05  MAGEC-DATE-THRU      PIC   X(12).
    05 MAGEC-DATE-THRU-FORMAT      PIC X(12).
    05 MAGEC-PLUS-MINUS-DAYS      PIC S9(5).
    05 MAGEC-LEAP-YEAR-CODE      PIC X.
    05 MAGEC-DATE-RETURN-CODE      PIC X(02).
      88 MAGDATE-OK      VALUE SPACES.
    05 MAGEC-RETURNED-DATE-INFO.
      07 MAGEC-DAY-OF-WK-CODE       PIC X(01).
      07 MAGEC-DAY-OF-WK-NAME       PIC X(10).
      07 MAGEC-MONTH-NAME       PIC X(10).
      07 MAGEC-END-PERIOD-FLAG       PIC X(01).
      07 MAGEC-GREG-DATES.
        09 MAGEC-GREG-MDCY       PIC 9(8).
        09 MAGEC-GREG-DMCY       PIC 9(8).
        09 MAGEC-GREG-CYMD       PIC 9(8).
        09 FILLER REDEFINES MAGEC-GREG-CYMD.
          11 FILLER       PIC X(2).
          11 MAGEC-GREG-YMD     PIC 9(6).
        09 MAGEC-GREG-MDY     PIC 9(6).
        09 MAGEC-GREG-DMY     PIC 9(6).
      07 MAGEC-JUL-DATE.
        09 MAGEC-JUL-DATE-CCYY     PIC 9(7).
        09 FILLER REDEFINES MAGEC-JUL-DATE-CCYY.
          11 MAGEC-JUL-DATE-CC     PIC 9(2).
          11 MAGEC-JUL-DATE-YYDDD    PIC 9(5).
      07 MAGEC-PERIOD-DATES-GREG.
        09 MAGEC-BEG-END-MONTH.
          11 MAGEC-BEG-MO-GREG     PIC 9(8).
          11 MAGEC-END-MO-GREG    PIC 9(8).
          11 MAGEC-BEG-MO-DAYOFWK     PIC X.
          11 MAGEC-END-MO-DAYOFWK     PIC X.
       09 MAGEC-BEG-END-QTR.
          11 MAGEC-BEG-QTR-GREG     PIC 9(8).
          11 MAGEC-END-QTR-GREG     PIC 9(8).
          11 MAGEC-BEG-QTR-DAYOFWK     PIC X.
          11 MAGEC-END-QTR-DAYOFWK    PIC X.
        09 MAGEC-BEG-END-SEMI.
          11 MAGEC-BEG-SEMI-GREG    PIC 9(8).
          11 MAGEC-END-SEMI-GREG     PIC 9(8).
          11 MAGEC-BEG-SEMI-DAYOFWK     PIC X.
          11 MAGEC-END-SEMI-DAYOFWK     PIC X.
       09 MAGEC-BEG-END-YR.
          11 MAGEC-BEG-YR-GREG     PIC 9(8).
          11 MAGEC-END-YR-GREG     PIC 9(8).
          11 MAGEC-BEG-YR-DAYOFWK     PIC X.
          11 MAGEC-END-YR-DAYOFWK     PIC X.

Your program must be linked to include the MAGDATE subroutine in order for you to call it. This is done in the link step of your compile jobstream. MAGDATE is found on the standard MAGEC library (loadlibrary, relocatable library, VSE/SP sublibrary, or in the \MAGMF directory).

The most basic function of the MAGDATE subroutine is date validation. You can pass it a date and a format specification (telling it what format the date is in). It will return with a return code of spaces (MAGDATE-OK) or another value indicating the type of error found in the date. You can also convert a date to another format, compare two dates to determine how many days apart they are, or project the date any number of days before or after a given date.

To do this you should understand the possible values of both the return code (MAGEC-DATE-RETURN-CODE), and of the format specification (MAGEC-DATE-FORMAT). Let us first examine the return codes. The copybook includes condition-names (88-levels) under MAGEC-DATE-RETURN-CODE, as described below.

The copybook includes condition names to define the possible return code values. They are:

              meaning

              successful completion of the requested action, the given date is a valid date in the format specified.

              the format specification is not valid

              input format was julian and the date given was not numeric

              input format was gregorian and one of the components was not numeric

              month of input date was not 01 through 12 - or JAN thru DEC

              the day number is not valid within the month (consider leap years for Feb.)

              input format was julian and the day number is invalid in the year given

              date comparison or projection was requested and the thru-date format is not valid

              date comparison of julian dates was requested and the thru-date is not valid

              date comparison in gregorian was requested and the thru-date is not valid

              date comparison was requested and the month of the thru-date is invalid

              date comparison was requested and the day of the thru-month is invalid

              date comparison was requested and the day number of the julisn thru-date is invalid

              date projection was requested and the number of days is invalid

The return code field is redefined as a numeric field (PIC 99) which is named: MAGEC-DATE-RETURN-CODE-N. This enables you to use the error codes as a subscript into a table of descriptions if you wish. Be careful not to try to use the good return code (blanks) as a subscript, however.

The format specifications which you can give describe the format of the date you wish to have validated, compared, or projected. In the MAGEC-DATE-FORMAT field enter one of:

In the above format specifications you notice that you can specify dates with or without slashes. The format specifications which include slashes actually describe a format in which slashes, or dashes, or spaces separate the date components. Thus, in a date format of MM/DD/YY a date of 02-21-91 would be accepted as valid The format specifications use mnemonic codes, i.e.

These same format specifications are used when you request for date conversions or comparisons. In those cases you give a format specification in both MAGEC-DATE-FORMAT and MAGEC-DATE-THRU.

The type of operation you request is determined by which of several of the fields within the request area you fill in, and which you leave blank (or zero). MAGDATE actually does all possible operations for the given date and fills in all of the returned date information regardless of what operation was requested.

It is legal for the two input dates, MAGEC-DATE-FROM and MAGEC-DATE-THRU to be in different formats for comparisons or projections.

You can use MAGDATE to validate a single date in any of the formats supported, to compare two dates of the same or different formats, or to project forward or backward a number of days from a given date. The type of operation is determined by which portions of the request area you fill in and which portions you leave blank (or zero). MAGDATE always sets the return code to indicate successful completion and that your input dates are valid or invalid. It also fills in all of the MAGEC-RETURNED-DATE-INFO fields if the return code is blanks (MAGDATE-OK), those fields are filled in with zeros if there was an error found in your input date.

To do a simple date validation, code:

MOVE SPACES TO MAGEC-DATE-REQUEST-AREA.
MOVE subject-date TO MAGEC-DATE-FROM.
MOVE date-format TO MAGEC-DATE-FORMAT.
CALL 'MAGDATE' USING MAGEC-DATE-REQUEST-AREA.
IF (MAGDATE-OK)...

In the above example "subject-date" is a dataname of a field containing the date to be validated, "date-format" is the dataname of a field containing one of the valid format specifications describing the date being edited.

To do a date conversion you would code exactly the same as above since MAGDATE always fills in all of the other fields in the request area. If MAGDATE-OK is true, you will have the Gregorian, Julian, and alpha-numeric date formats, plus the day-of-week, period ending dates, and leap year flag set. A value of "Y" in MAGEC-LEAP-YEAR-CODE indicates that the date is in a leap year.

To compare two dates to see how many days apart they are, code:

MOVE SPACES TO MAGEC-DATE-REQUEST-AREA.
MOVE subject-date1 TO MAGEC-DATE-FROM.
MOVE subject-date2 TO MAGEC-DATE-THRU.
MOVE date-format1 TO MAGEC-DATE-FORMAT.
MOVE date-format2 TO MAGEC-DATE-THRU-FORMAT.
CALL 'MAGDATE' USING MAGEC-DATE-REQUEST-AREA.
IF (MAGDATE-OK)...

In the above example "subject-date1" is a dataname of a field containing one date, "subject-date2" is the dataname of a field containing another date, "date-format1" is the dataname of a field containing a valid format specification describing subject-date1's date, and "date-format2" is the dataname of the field containing subject-date2's date format specification. Upon return from MAGDATE, if MAGDATE-OK is true, you will have all of the other fields of the request area filled in and the field named MAGEC-PLUS-MINUS-DAYS will contain the number of days between the two dates. If the thru-date is earlier than the from-date this value will be negative. The date information and period ending information will apply to the thru-date, not to the from-date.

To do a date projection, code:

MOVE SPACES TO MAGEC-DATE-REQUEST-AREA.
MOVE subject-date TO MAGEC-DATE-FROM.
MOVE date-format1 TO MAGEC-DATE-FORMAT.
MOVE date-format2 TO MAGEC-DATE-THRU-FORMAT.
MOVE number-of-days TO MAGEC-PLUS-MINUS-DAYS.
CALL 'MAGDATE' USING MAGEC-DATE-REQUEST-AREA.
IF (MAGDATE-OK)...

In the above example "subject-date" is the dataname of a field containing the date you wish to project from, "date-format1" is the dataname of a field containing a format specifiction describing the date in subject-date, and number-of-days is a numeric value between -99,999 and +99,999. MAGDATE will calculate the date projected either forward or backward and place it into MAGEC-DATE-THRU in the format specified in "date-format2".

There is an online demonstration screen which uses MAGDATE. It allows you to enter into the various request area fields from your keyboard and to see the results immediately. This can be useful in learning how to use MAGDATE. It can also be used to convert or project dates for whatever purpose you might desire.

The online MAGDATE demonstration can be invoked using the function code: **DATE

No key value is required, you will be able to type into the labelled screen fields which correspond to the request area fields. This is a fast way to learn how to use MAGDATE and to see exactly how all of the date information is returned from MAGDATE.

In validating and converting dates MAGDATE is cognizant of the fact that leap years are 366 days long and that leap years are years which are divisible by four, except that years which are also divisible by one-hundred are not leap years unless they are divisible by four-hundred. The year 2000 is a leap year, but the years 1900, 2100, 2200, and 2300 are not. When a 2-digit year format is given with a year of 50 or greater, MAGDATE assumes that the date is a 19xx year; if the year is less than 50 it assumes it is a 20xx year.

The day-of-week codes in all cases are values from 1 through 7, where 1 = Sunday, 2 = Monday, 7 = Saturday, et cetera.

The Mask copybook which MAGEC generates for your screen Mask includes definitions for all your screen fields plus definitions for all the necessary control fields associated with them. For each field (assuming a screen field named "Sfield") it includes:

For numeric edit-type fields:

For date edit-type fields:

For color-controlled fields:

You can reference any of these control fields in your MMP. Your MMP's automatically have symbolic names defined for all the valid colors and extended highlighting options. They are:

Colors:

Highlighting:

When you are coding customization logic for your MMP's, you will usually be more familiar with the database field (DIT) datanames than with the screen field (MSK) datanames. For that reason, you may prefer to utilize MAGEC's Symbolic Screen Field Referencing feature which is described in detail in the "Database Administration" chapter of the "Programmer's Reference Guide.

Briefly, it enables you to use the database name to indirectly access screen fields. The mapping of database names to screen field names is controlled by the associations defined in the screen's Mask definition. The associations are defined using the "Source/Target" specifications for screen fields.

Assuming that you had a screen field named SAMOUNT with a source/target named CUS01-AMOUNT, you could code:

MOVE +10.00 TO @CUS01-AMOUNT@-N @CUS01-AMOUNT@-ED

MOVE RED TO @CUS01-AMOUNT@-COLOR

rather than having to look up the screen field name (SAMOUNT) in order to access it.

MAGEC will, as the program is being generated, translate the symbolic references into the proper Cobol datanames. You can append any of the appropriate suffixes to the symbolic reference, as shown above. Assuming that the screen field having CUS01-AMOUNT as its source/target is named SAMOUNT, the above coding would translate into:

MOVE +10.00 TO SAMOUNT-N SAMOUNT-ED

MOVE RED TO SAMOUNT-COLOR

Symbolic references are a good way to access screen fields in routines which are to be stored as copybooks to be included into many programs. This way you are not concerned with knowing the datanames used for screen fields in several places, your coding becomes more "portable".

NOTE:

• You should read the topic, Symbolic Screen Field References in the "Database Administration" chapter before coding symbolic references. This feature was provided primarily for the coding of Business Rules and Referential Integrity Rules, however, it is also available to Application Developers.

In order to generate MMP's which access an SQL database, such as DB2, you must provide customization coding (using SQL) to replace the default I/O routines. You could do this manually, or you can have MAGEC generate the necessary customization coding automatically. The automatic generation process is online and involves only a single online command:

SQLCRE nnn

where nnn is the Mask# (SHD number) of the application for which you wish SQL accesses generated.

The SQLCRE function will automatically generate customization for all of the I/O insertion points. They are:

%ADDIT
%DELET
%LOCKY
%REDNX
%RDUKY
%REDKY
%UPDAT
%RELES


and for two other insertion points where it is necessary to define the host variables and to move them to and from the standard MAGEC data definition copybook. The two other insertion points are:

%LITERAL
%SUBRTNM


The customization will be added to the dictionary with names which include modifiers to identify them as generated code. The modifiers will all be "MAGECSQL". For example, for application 600 there would be customization generated as:

600/ADDIT/MAGECSQL
600/REDKY/MAGECSQL
et cetera

If you modify these generated routines you should be aware that re-executing the SQLCRE command will overlay your modifications with newly generated, unmodified routines.

The generated code assumes that there is a member defining the host variables for each Element accessed stored on the MAGEC library. The member must have a name of

eeeee-c/SQL

where eeeee is the element name. Such a host variable definition library member will be generated by the DITGEN function (see the Data Definition tutorial) automatically, if the Data Class has an access method of SQL or DB2 specified.

If you have generated an application for SQL and wish to revert it back to VSAM, or some other access method, you must remove all of the SQL customization. This allows the application to be re-generated using the default logic which accesses the MAGEC I/O module.

To remove the SQL customization, you could either manually delete it piece-by-piece; or you could use the SQLPUR (SQL Purge) function to remove all of it in one fell swoop. The format is:

SQLPUR nnn

where nnn is the applications's Mask number, as before. Any modifications you nave made to the generated SQL routines will be deleted along with the routines since the SQLPUR function erases all customization code for the specified application which has a modifier of MAGECSQL.

The generated SQL customization is for the Primary Data Class only. The Primary Data Class may be a single table or it may be a view, joining several tables. Restrictions of your database management system may prevent updates or deletes whcn accessing a joined view, rather than a simple table.

If you wish, you can do standard MAGEC joins of multiple tables, thereby circumventing the database management system's restrictions against updating joined views. To do that you would code SQL accesses to other tables in the standard %JOIN insertion point, or elsewhere in the MMP's logic. MAGEC will not automatically generate such accesses; however, the built-in Named Proforma facility will help you quite a lot since it contains all the SQL command formats pre-coded for you.

SQLPUR will not purge any customization except for that which has the MAGECSQL modifier, and is in the designated insertion points (listed earlier). Your manually added SQL code in other insertion points (such as %JOIN), or with any other modifiers, will not be purged!

As of release 2.6, MAGEC has added the Attach/Detach facility which provides a standardized technique for coding "nested" screens. Nested screens are simply a sequence of screens wherein the operator can be entering into one screen and can "pop-up" another screen and then return to the first screen with all data as it was left and with the ability to pass information from one to another.

Some people would use the nomenclature "push/pop stack", or "call/return", to describe MAGEC's Attach/Detach facility. The name "Attach/Detach" is intended to avoid confusion with any other existing facility of CICS or other environmental software.

An Attach is a call from one transaction to invoke another transaction, retaining all data necessary to enable the lower-level transaction to Detach, or to return to the calling transaction.

This facility supports multiple levels of nesting. The Attach function preserves TWA data, file positioning, and screen data for the transaction so that control is passed back to it in the same status as it was left. The transactions are also able to pass data back and forth.

The Attach/Detach facility is particularly beneficial when used in conjunction with the MODELWIN feature which generates pop-up windows applications. A full-screen application can easily Attach to a pop-up window application which can perform any number of processes, then Detach back to the full-screen application which invoked it.

Rather than using the FTH-FUNCT (Fetch Function) command, which would require the programmer to save and restore TWA data for each task, using Attach/Detach automatically saves and restores the TWA as appropriate and supports passing data from one task to another.

The Attach/Detach facility retains much of the feel of existing MAGEC facilities, in fact, it is very similar to fetch function (FTH-FUNCT) which is a well known and established MAGEC programming technique. The facility uses existing MAGEC common areas, i.e. the common screen fields, SFUNCT, SKEY, SERRMSG, SCOMPL, and TWA-MSK-AID are in the same relative positions in every TWA, thereby making them the ideal common areas for the applictions to use. There is also the benefit that the use of these fields is completely environmentally neutral, creating no CICS dependencies. Having an unlimited number of levels introduces the problem of too much overhead, so a limit of thirteen (13) levels is designated as being sufficient for most needs. The facility should be usable from either of the active MAGEC windows (swapping windows is done using the PF9 key) at the terminal and each session is completely independent of the other. For simplicity, protocol requirements of individual applications are the application's responsibility. The system also supports user-initiated cancellation of the dialog, clearing the "stack". This is basically consistent with the concept that any transaction dialog under CICS can be interrupted at any time due to the nature of pseudo-conversational programming, VTAM, or hardware errors.

The Attach/Detach facility operates much in the same manner as the MAGEC "Fetch Function" facility. Unlike a fetch function, when an application attaches another application, the requesting application's usable TWA is saved before entering the other application program. Upon returning from the attached application, the original TWA is restored to its state as it was when saved immediately before the attach was done except as noted below. In order to invoke an Attach, the application program uses a sequence of code as follows:

As you can see from the above, invocation of this facility is much like using the FTH-FUNCT logic. The desired function code and key value are placed into the standard screen fields as if they had been typed into those fields by the operator.

The return from the attached function to the (next higher) invoking function is also quite similar to the FTH-FUNCT coding, except that the returning function need not know the identity of the attaching function. An example of the required code is as follows:

This sequence instructs the Attach/Detach service module to return to the next highest level, i.e.: restore the TWA of the invoking function and give control back to that function (at the top of the Procedure Division, not the "next-sequential instruction").

In order to pass information from task to task, the system requires the ability to pass parameter information and retrieve the returned information. To accomplish this, the Attach/Detach facility uses the standard MAGEC screen fields as communication areas. We have already discussed the use of SFUNCT and SKEY in the examples above. In addition, SCOMPL is used by the attach/detach facility to provide information about the function being performed. This field has a structure as follows:

The value of these fields depends on the last type of request made; i.e.: if an Attach was done then the first field contains the literal "ATT". After a Detach it contains the value "DET". The remaining fields contain the last function and the last key processed by the program requesting the Attach/Detach service. This information may be used by your program to determine the validity of a particular dialog, i.e.: perhaps only certain programs should attach certain other programs.

The SERRMSG field is used as a communications area between functions. Note that communications is optional, not mandatory. This 240-byte field may be structured in any manner required by the participating applications. To do so, the applications should contain an area with the desired breakdown or definition and should MOVE SERRMSG to (and from) that area. It is up to the application designer to specify the desired definition for this area. There are two recommendations that are made with respect to this area:

The value of SERRMSG is passed "down" and "up" the dialog by the Attach/Detach facility. Please note that if you wish to retain the original value of this area, or SCOMPL for that matter, before attaching another function you should move this field to an area defined in the %DATADEF customization point or, alternatively, you could merely rebuild it from the original information (usually values in the %LITERAL customization). Although this area is somewhat limited in its size (240 bytes), it can be used quite effectively. If the attached dialog was doing a codification look-up, the only information required to be sent back to the attaching function is the key of the record selected, not the entire record. The receiving transaction can always reread the record in question to obtain additional information. Conceptually, information passed in this manner is far more atomic than one might suspect initially. Conventional CICS DFHCOMMAREA processes generally tend to pass far more data. The original attaching program's TWA area will be preserved; therefore there is never any need to pass along any of that information to the attached module. In fact, upon entry to the attached module, the TWA will contain the contents of the attaching programs area. This area will always be completely restored upon detachment. Of course the values of TWA-MSK-AID, SCOMPL, and SERRMSG area will be altered as cited above. Applications which require massive cross communication of TWA information can be developed but need to be rigorously architected to insure that the TWA areas conform. One technique for passing very large amounts of data is to write it to a record on a file, passing the key to the target transaction.

We have discussed the basic method of invocation of the attach/detach facility and the communications areas used in the process. We should now discuss the additional information available to the application designer/programmer to control this facility. There are a series of COBOL 88-Levels in the TWA which may be interrogated to determine the current status of a dialog. The below series of code examples illustrate the use of these conditionals:

The above examples show the various things that can be done by interrogating the current status of the session. The third example shows how a program can push itself to the top of the attach list. Note that this also occurs automatically any time the terminal user causes the MAGEC clear screen to be invoked, or when a MAGEC menu function is used. The application users can escape a dialog at any time they desire. Logging on (via the SYSLOG function) also results in the session being established at the "top" of the attach dialog (clearing the stack). Additionally, if the application does not make the check to see if it has been attached, and then subsequently issues an invalid Detach request, an error code is displayed. Attempting to attach another function when you are already at the lowest level results in a pop-up window offering the operator four options for handling the situation. 1) push the oldest screen off the stack, 2) clear the stack, 3) transfer the screen without adding the current screen to the stack (using a FTH-FUNCT, instead of an Attach), 4) return to the original screen.

A common (false) impression that many developers get when first introduced to MAGEC is that it does a great job of developing single-screen transactions; but doesn't seem to handle applications which involve multiple screens. An example of such a multi-screen application would occur when the data to be added/updated is more than can be placed on one screen. In this example it is necessary to create multiple screens to capture or present all the data before any I/O request to update the file(s) or table(s) is issued.

Actually, multi-screen processing is quite simple with MAGEC. In fact, the entire application development process which was used throughout these turorials is merely a collection of MAGEC-generated applications which link to one another. We might recall the initial phases of the development process (refer to the "Application Developer" chapter of this Tutorial manual) wherein we were automatically transferred from one panel to the next in order to capture the complex set of specifications needed to create our screen and application. The entire process consists of MAGEC-generated, Cobol applications programs, not much different from ones any programmer using MAGEC might have produced. They use the same standard facilities which are available to all MAGEC-generated programs.

For the purposes of our discussion, let us assume that we need to develop an application which accomplishes the standard functions to maintain a file which has records which contain more data than will fit on one screen. For simplicity, we will assume that two screens will suffice; though there is really no limit on the number of screens possible.

There are basically two philosophies which can be applied to solve this problem. First, we could build a multi-screen application which captures all the needed data, edits it all, then adds/updates it to the database. Second, we could build an application which contains a "first" screen which captures some of the data, edits it, and adds/updates the database with what it has, then links to a "second" screen which captures the remainder of the data, edits it, and updates the database with that data.

The advantage of the first approach is that no incomplete data ever reaches the database. All fields are fully edited and validated, both individually and in context with one another, before any of the data is accepted and recorded.

The advantage of the second approach is that, in the event of an interruption, the sequence can be resumed at the point where it was left off. Examples of interruptions would be: power failure, operator error which exits the sequence, software abend, etc. With the first half of the data safely recorded to the database, it is a relatively simple matter to restart from that point forward. The only data which will be lost is that which was typed onto the screen but not yet updated to the database.

The disadvantage of this second approach is that it adds the responsibility of writing an audit program which searches for and reports any incomplete data on the database. This disadvantage is not nearly as great as it might sound, however, since any thorough design for an online system which manages important data will include a database audit program, anyhow. It should be recognized that no amount of diligence in any online system can prevent every possible database integrity error condition from occurring. Physical disk errors, human errors while using offline utility programs (backups, restores, reorganizations, etc.), software bugs (perhaps in system software), and many other types of problems can, and do, still occur .

To implement the first approach is not very complicated at all. First we would create two applications, one to process the first half of the data, one to process the second half. Each would have its own screen Mask and its own MMP. Each would also have its own full set of function codes. The function codes must be unique, therefore we would specify a different function code prefix on the Screen Header for each of these two applications, even though both would have the same primary Data Class.

If we assume that the file we are accessing/maintaining is a customer file with a Data Class ID of CUS, we might specify the function code prefix of CUS for the first application and a function code prefix of CS2 for the second. Both would specify CUS as their primary Data Class. They would also both have the same list of Elements from that Data Class, even though each might only need a portion of the complete set of customer data.

In the first MMP we would wish to customize the logic so that it:

To do this is quite simple. There are insertion points provided to allow developers to override the default database update, or add processing. What we wish to do is to override them with a fetch to the second MMP, with the appropriate function code set. For example, if we were adding customer data in the first screen (function code CUSADD), we would want to fetch to the second MMP with a function code of CS2ADD. If we were updating in the first MMP (function code CUSCHG), we would want to fetch to the second with a function code of CS2CHG, and so forth.

The two insertion points involved are:

The code you could provide into each of these insertion points to accomplish all of the above objectives might be:

TEST-FUNCT-KEY is the first three bytes of TEST-FUNCT, which contains the same value as SFUNCT. By setting the first three characters to CS2, leaving the last three characters alone, we have built the appropriate function code to fetch to. The remainder of the above code is the standard FTH-FUNCT logic (refer to "Appendix B in this chapter).

Notice that is was not necessary to do anything at all to pass data to the fetched MMP. MAGEC automatically passes the entire TWA. All the data which was captured from the first screen has already been moved into the appropriate record fields in the Element copybook(s) in the TWA. Upon entry of the second MMP, the entire TWA will contain all the data placed in it by the first MMP. Since the programs have the same list of primary Elements, their TWA-DB-DATA areas are defined the same.

It should be noted that the standard logic on an ADD function includes initializing the Element copybook areas to spaces before moving data from the screen to the Element copybook fields. This means that any unreferenced fields will have a predictable value, spaces. If another value is desired, the developer should provide customization for the insertion point %ADDINIT.

The second MMP will need to know that it is being entered from the first. It is not unusual in these situations for the developer to specify that it is illegal to access the second MMP without having come from the first. To ensure this, the developer could add customization into the %PREINIT insertion point, as follows.

The above code will ensure that we have come from the first screen, and for the same key value. If not, it will fetch back to the first screen to try to initiate the sequence at the beginning, on the assumption that that is what the operator should have done (meant to do) anyhow.

The second MMP will also need to refrain from re-reading (or trying to read) the record being processed. This is because the first MMP has already read it and the entire record (or, at least, all the Elements we are interested in) are already in TWA-DB-DATA; reading on top of them is both unnecessary and destructive. To suppress those reads we might simply comment out the perform of the I/O call in the insertion points: %REDKY and %RDUKY, as:

We also must prevent the default %ADDINIT logic in the second MMP from trying to initialize the Element copybook fields. To do this we would simply add customization into the %ADDINIT insertion point commenting out the MOVE SPACES... code.

The second MMP will follow its natural flow and, if all edits are passed, add or update the database record with all the data from the first and second screens.

In the second approach we allow the standard logic of the first MMP to do its normal update or add, then we have it fetch to the second MMP. Since, on an ADD function, the record will be added in the first MMP, we will transfer to the second using a CHG function whether we were doing an ADD or a CHG in the first MMP.

Because we will be adding an incomplete set of data to the database in the first MMP, we should be careful to set appropriate default values into all the fields of the Element copybook(s) being updated. That means that we might need to put some customization code into the %ADDINIT insertion point. The customization would move default values to those fields not updated/added from the first MMP. Some developers will choose to set default values which identify this record as "incomplete" in order to facilitate auditing the database and/or restarting the multi-screen transaction from the point it was aborted.

The first MMP should fetch to the second from the %GOODADD and %GOODCHG insertion points. These insertion points occur after a successful add or update, respectively. The coding to fetch to the second MMP would be:

In this case, we are always fetching to the CHG function for the second MMP since the record is already on the database, having been just added or updated by the first MMP. It is not necessary to suppress the normal reading in the second MMP, for the same reason.

What should be done, though, is suppression of the ADD function in the second MMP. This is done by simply de-selecting the ADD function from the list of available functions for this MMP. Refer to the MMP header screen discussion and Figure 02 inthe Application Developer section of this book. The Application Developer section is the first index tab in this Tutorials manual. Removing the ADD function in this manner prior to generating the MMP causes MAGEC not to generate a FCD (Function Code) definition record for an ADD function and also suppresses the generation of code into the MMP to support an ADD function.

It is possible to use the same coding in %PREINIT to ensure that the operator begins on the first screen before getting to the second screen; however, it is not necessary. Using this approach there is not a real reason why an operator should not directly access the second screen, if desired. An ADD function, of course, must begin from the first screen. That is ensured by the fact that the second screen has no ADD function at all.

In either approach it might also be appropriate to provide a PF key in both MMP's to "swap" from screen one to screen two, and vice-versa for SEE functions. It would be acceptable (maybe preferrable) to use the same key in both such that it "toggles" between the two screens. Such coding could be done in the insertion point %PFKEYM. It would use the standard FTH-FUNCT logic as described in "Appendix B and the PF key logic as described in "Appendix G, both of this same chapter. It might also be advisable to restrict this toggling only to SEE and NXT functions via the condition name provided, i.e.:

Some developers are accustomed to creating one program which utilizes several screens, rather than creating separate programs as described above. MAGEC supports the use of multiple screen Masks in any MMP; however, it is not recommended.

When a program, whether it is a MAGEC-generated program or not, utilizes multiple screen masks, the definitions for those masks must redefine one another. The CICS "map set" facility is a good example of screen definitions redefining one another. This redefinition opens up the possibility for many types of programming errors and greatly complicates both coding and debugging of the programs.

The program which utilizes multiple screens must constantly be aware of which screen format is active at any given time and must not make any references to screen fields not contained in the active screen mask.

At first glance it might seem that the technique of creating separate MMP's for each screen in a multiple screen sequence is less efficient; however, because of the architecture of MAGEC, it is approximately as efficient as a single program using multiple screens. The simpler, more modular, structure of the separate programs also eliminates the need for procedural logic to distinguish between the various screen formats in order to prevent references to an inactive screen from common routines.

Maintainability of the simpler programs is as good as for any ordinary MAGEC-generated program, since there is very little customization involved. It is even possible to add additional screens into the sequence with very little difficulty.

For various reasons, you may occasionally wish to interrogate the Global Parameters table of MAGEC from your application programs. That enables you to see exactly what settings have been specified for your MAGEC installation, and to take action accordingly. One example of why you may wish to access this information would be to learn what highlighting option has been specified for error fields on a screen (for 7-color terminals). We will use that example to illustrate accessing the table. Of course, any of the other parameters could be accessed similarly.

It is possible, but not recommended, to update the table from your programs. The reason it is not recommended is because the intrinsic functions provided with MAGEC to maintain the table include appropriate editing and formatting which your program might not adhere to; thereby creating an error condition. The intrinsic functions are:

There is a discussion about Table #243, Global Parameters, in the Installation Guide.

Table #243 is merely a standard MAGEC Lookup table. It can be accessed just as any other table can be accessed, by reading the TBL file. To properly access this table, you should include the standard copybook into your program to define the TBL file records. To do that, code:

This would usually be in the %DATADEF, or %VARSTOR, insertion points.

In your Procedure Division, you should place code to read the file. For example, in an MMP:

Remember to check in the "Insertion Points chapter of your Programmer's Reference Guide to determine whether it is necessary to save and restore the I/O request area when doing I/O in the insertion point you choose. In %EDIT or %JOIN it is not necessary, for some others it may be.

You might frequently find it useful to develop screens on which the operator maintains multiple records from a single transaction. Such a screen typically lists records much like the browses do, but allows the operator to modify the listed records on the screen. The program senses which records were modified on the screen and updates, adds, or deletes accordingly.

An example of a function which might work this way is an Accounts Payable screen which shows the vendor information at the top and lists open invoices below. The operator might be allowed to modify the Release-to-Pay date on one or more of the invoices. He or she might also be allowed to delete invoices by typing a code into a designated field on that invoice's line, or to add new invoices by typing them into blank lines shown below the last open invoice on the screen. Such a program would read (and likely update) the vendor master record as well as one or more invoice records.

While this process might seem very different from the standard MAGEC-generated functions, it is not difficult to create. It requires surprisingly little customization to do so. Here is one technique which many MAGEC customers have used to develop hundreds of list-update MMP's. You may wish to modify this technique to accommodate some special requirement of your own. Once you have developed your first list-update program you will likely use it as a model for many other similar programs.

Before we discuss the technique it is helpful to review a few of the standards employed in the generated MMP's. Regardless what type function is being processed, the generated MMP's are designed to build a "logical record" or "view", then to do the desired process against the data within that logical record. In other words, the program reads one or more files or tables, calculates derived values, and places all of the resulting data into predictable locations (usually that means in the appropriate element copybooks in %DATADEF) early in the processing cycle. Thereafter, the logic is unconcerned about from whence the data came; all data is available to use however necessary.

An example of that is the Vacation MMP (MMP600) which you developed in these tutorials. It gathers data from two files (VAC and SIF) plus derived values (the calculated days due). The %JOIN insertion point is used to build the logical record.

If you have reviewed the Screen Painting section of your Programmer's Reference manual, you should have noticed that MAGEC allows you to easily define "repeating fields" on a screen. These repeating fields constitute an array, or table which is accessed using a Cobol subscript or index. You can have more than one such array on your screen. You can specify as the Source/Target database field for these repeating screen fields any valid Cobol dataname which OCCURS. It is perfectly legitimate for the Source/Target field to be a "Working-Storage" field, rather than an actual database field. You specify a relative subscript using an asterisk " (*) " to denote that the corresponding occurrence of each screen field and its Source/Target field will be MOVE'd to one another at the appropriate times.

All of the routines which do I/O in the MMP can be modified by you using customization in insertion points such as %REDKY, %RDUKY, %UPDAT, et cetera. When you add customization logic into these insertion points, MAGEC presents a proforma on the screen which strongly resembles the default I/O logic. This facilitates your making modifications to the I/O logic without having to re-type the default code.

While there are probably many ways to skin a cat, professional developers usually find one good way to do something, then adopt it as a standard and use it many times over. Below is a technique which was developed by some accomplished MAGEC users and has been shared with many others.

Specifications

For this example we will assume the vendor/invoice problem referenced earlier. The screen is to show vendor data at the top and is to list ten (10) invoices below. To the left of each invoice there is to be a one-byte action code into which the operator will type "A", "C", or "D" to cause an add, change or delete of that invoice. The standard MAGEC PF7 and PF8 keys will bump to the previous or next vendor, the PF4 and PF5 keys will scroll backward or forward through this vendor's invoices.

The vendor file is keyed by vendor number, the invoice file is keyed by vendor number plus invoice number concatenated. The vendor number must already exist on the vendor file, thus this program will have only SEE and CHG maintenance functions. To add or delete vendors the operator will have a different vendor maintenance screen.

Auto-Join

To begin, you define the screen and MMP headers just as you would for any other new application. You specify the vendor file as your primary data class. Using the fully-automated development process to create the screen, you select the invoice file for MAGEC to join to. Note, this presumes that the vendor number is the high-order portion of the invoice file key and that it belongs to the same domain as the vendor number in the vendor file. MAGEC will generate a partial-key join to the invoice file; that is, it will generate (in %JOIN) a LOCKY, REDLE to read the first invoice for this vendor. You will be able to customize this join to then do REDNX to get subsequent invoices. If you are not familiar with these database I/O commands, refer to the Database Administration section of your Programmer's Reference manual.

Screen Painting

After you have selected the fields (Data Items) you wish to present on your screen from both the vendor and invoice record elements, MAGEC will generate a screen containing fields to display one vendor's data and one invoice's data. Using the manual screen painter, arrange the vendor data at the top of the screen and arrange the invoice data across one line. delete the screen prompts which were generated to the left of each incoice field, you will be drawing a column heading above the invoice fields to replace these prompts. Leave one blank line (optional) below the vendor data, plus one line for the column headings. Place the invoice fields on the next line below the column headings line. Manually draw one column heading field with appropriate literals in the line immediately above the invoice data line.

Modify each invoice field by cursor-selecting it using PF18. Change the Occurrence to "*10", this will cause MAGEC to repeat that field ten times vertically. Of course, if you wished to have other than ten occurrences, you would modify the entry into Occurrence. Also modify the Source/Target to be an arrayed Working-Storage field, rather than the database field name which was generated for you. For ease of understanding, you should use a similar name with only the prefix altered. For instance: if the database name was IVC01-AMOUNT, you might alter it to WS-AMOUNT (*). The asterisk in the subscript tells MAGEC to generate MOVE's back and forth between the arrayed screen fields and their corresponding occurrences of "WS-" fields. Do not forget to add a one-byte Action-Code field which OCCURS just like the invoice fields. Its Source/Target might be WS-ACTION (*).

%DATADEF

Define a table of Working-Storage Source/Target fields. Use Cobol level 03 for the group item defining the entire table. Use Cobol level 05 (or as desired) for the entry below the group item. This 05 item should contain the OCCURS 10 TIMES clause. Define each "WS-" field using Cobol level 07 below it. Also define an index or subscript [PIC S9(4) COMP SYNC is recommended].

MAGEC will generate MOVE's from the fields in this table to the screen for displays and from the screen fields to this table for updates. For all intents and purposes, MAGEC now "thinks" this table is the database record which was read or will be updated. Do not forget the action code which also occurs.

Be sure to include all the primary key fields necessary to read each invoice record. If some of the key fields will not be displayed on the screen, include them in the table anyhow--you will need the complete primary key to add, delete, or update these records.

Also, add a field in %DATADEF to store the "beginning invoice number". This field will be used to start the browse looking for invoices for this vendor.

%REDKY

The default logic here does an exact key read of the vendor record, then it performs the join logic. Add one line of code before performing JA100-LOGICAL-JOIN to set the beginning invoice number to zero.

%JOIN

In %JOIN you will find generated logic to read the first invoice for the vendor being processed. That means that at the bottom of this generated join logic you will have the vendor data and one invoice's data in their appropriate element copybook areas.

First, alter the logic which builds the generic key for the invoice records. The generated logic fills in the high-order portion of the key using the vendor number and sets the low-order portion (the invoice number) to zeros. You must move the beginning invoice number from your %DATADEF holding field into the invoice number portion (low-order portion) of the key. This results in positioning to the first invoice for this vendor having an invoice number equal to or greater than the beginning invoice number.

Next, you must initialize the "WS-" table which you have defined in %DATADEF. In Cobol II you may use the INITIALIZE verb, or you may move appropriate spaces or zeros in older Cobol implementations.

Next, you must move the appropriate fields from the first invoice record into the first entry of the table (occurrence 1). Be sure to move the key fields into the table entry. Set the subscript or index to 1.

Then, you must do the REDNX I/O command to get the next invoice, increment the subscript, and move its data to the table entry using that subscript. You loop back through this REDNX processing. Of course, you will test for your subscript reaching the end of the table or your REDNX getting a NOT-FOUND, or reaching an invoice for the next vendor to know when to stop looping.

At the end of this, your table will be loaded with invoices. Any unused entries at the bottom of the table will contain the initial values you set earlier. The action codes will all be set to their initial value, normally spaces.

%RDUKY

In this insertion point the defailt logic reads the primary record (vendor record) for update, getting exclusive control of it; then performs the join logic. Reading for update is a prerequisite for updating or deleting a record. If you will be updating the vendor record, leave the RDUKY for it alone, but remove the perform of JA100-LOGICAL-JOIN. If you will not be updating the primary record, also remove the perform of AA840-CALL-MAGEC-IO. The reason you do not want to re-do the join logic is because 1) it is unnecessary since the data is preserved in your table in %DATADEF, and 2) you do not yet know which, if any, of the invoice records will be updated, deleted, or added--that will be determined later in %UPDAT. If you remove the call to AA840-CALL-MAGEC-IO you should replace it with MOVE SPACES TO TWA-DB-RETURN-CODE, or SET REC-FOUND TO TRUE.

%UPDAT

In this insertion point the defaiult logic updates the primary record (vendor record, in this example). If you do not want to update the primary record, remove the call to AA840-CALL-MAGEC-IO and move spaces to TWA-DB-RETURN-CODE (or SET REC-FOUND TO TRUE). Next, you will code a routine to loop through your table interrogating the action codes to determine whether to add, update, delete, or ignore each invoice.

For each invoice to be added, you must do the ADDIT I/O command after moving the fields from the appropriate occurrence in the table to the invoice element copybook. Be sure to fill in all key fields completely--in some designs this would involve reading a control record to assign the next available invoice number.

For each invoice to be deleted, you must do the RDUKY I/O command followed by the DELET I/O command.

For each invoice to be updated, you must do the RDUKY I/O command, then move the fields from the table to the invoice element copybook fields, then do the UPDAT I/O command.

It is important to save the TWA-DB-REQUEST area into TWA-DB-REQ-SAV after the primary file's I/O and before your routine to update the joined file (even if you have removed the call to update the primary file), and then to restore it to TWA-DB-REQUEST after you have finished looping through your table. The standard logic of the MMP expects the TWA-DB-REQUEST area to reflect the status resulting from the update of the primary file after exiting from this point in the program.

As you are updating, adding, or deleting records based upon the action code on the screen you should also be setting the action code off (by moving space to it) for each item. You may prefer to move something to the screen indicating which lines were processed, as well.

%GOODCHG

The default logic in this insertion points will set a message into SCOMPL indicating successful completion and will fetch to the SEE function to display the results of the changes. You may not wish to execute the SEE function, but rather just send the screen as is with any messages or statuses you have inserted into the array to show what was added, changed, or deleted. To accomplish that you should merely remove the line of code which says: MOVE FTH-FUNCT TO TWA-NONTP-REQUEST. The program will still change the function code in SFUNCT to the SEE function, but will not execute the SEE function. It will just send the screen as is.

%PFKEYM

The default logic for handling PF7 (page back to prior vendor) and PF8 (page forward to next vendor) will remain intact. It works just as we want it to. We will, however, add logic to handle PF4 (scroll up the list of invoices) and PF5 (scroll down the list of invoices). The scrolling operations will limit themselves to only those invoices which belong to this vendor. The invoice scrolling depends upon the fact that you have the table in %DATADEF which contains data for each invoice listed on the screen, including the invoice numbers.

For PF5, move the invoice number from the last invoice listed on the screen into the %DATADEF field used to hold the beginning invoice number, add one to it, then perform JA100-LOGICAL-JOIN THRU JA199-EXIT, perform BB200-FILL-SCREEN thru BB299-EXIT and GO TO AA800-SEND-SCREEN.

For PF4, you do a similar process, except that you must use the invoice number from the first invoice listed on the screen, then do the REDPR I/O command to "back up" ten invoices (or until you reach the Beginning-of-File or an invoice for another vendor) to obtain the appropriate beginning invoice number to start listing from.

It may also be prudent, prior to accepting a PF4 or PF5 or PF7 or PF8 key) to add a check of the screens action codes for each invoice listed on the screen to see if any were marked for database action. If any were marked, you might wish to ignore the scrolling or paging by resetting the key to ENTER, as: SET TWA-MSK-ENTER-HIT TO TRUE, or MOVE QUOTE TO TWA-MSK-AID. This must be done before the processing for PF4 or PF5, obviously.

The technique discussed above has been successfully used many times. You may wish to modify it with your own refinements. One common modification is to eliminate the action code on each detail line of the screen and compare the screen data to the data in the "WS-" table to determine if anything has been altered. You might retain the action codes in the "WS-" table and set them to "A", "C", or "D" internally. A delete might be indicated by finding a zero invoice number on the screen corresponding to an occurrence in the table which is non-zero. An addition might be indicated by finding a non-zero invoice number on the screen corresponding to a zero entry in the table, and so forth, a change might be indicated by finding the same invoice number on the screen for its corresponding table entry, but with other values on that line altered from what was in the table.