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.
DO THIS: |
Sample Project 1
DO THIS: |
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: |
TSKLST 600 PF8 = next page -- PF5 = Page 1 |
DO THIS: |
You will be transferred to the Customization Algorithm ADD screen for inserting coding into
VARIABLE-STORAGE in the LINKAGE SECTION.
TSKLST 600 PF8 = Next Page -- PF5 = PAGE 1 |
DO THIS: |
ALGADD 600/VARSTOR |
with Proforma Code Displayed
DO THIS: |
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: |
NOTE:
ALGADD 600/VARSTOR |
The TSKLST (page 1) will appear.
Entering Procedure Division Code
DO THIS: |
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: |
TSKLST 600 PF8 = Next Page -- PF5 = PAGE 1 |
DO THIS: |
You will be transferred to the screen showing the existing code which is on file.
TSKLST 600 PF8 = next page -- PF5 = Page 1 |
NOTE: The status of the %JOIN customization task shows "1 DONE", meaning that there is one "page" of customization coding in the repository for the insertion point, for this application. Since you have not done any customization for %JOIN yet, you might wonder how that could be correct.
DO THIS: |
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:
ALGNXT 600/JOIN/01-SIF/000 |
DO THIS: |
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.
ALGNXT 600/JOIN/01-SIF/000 Press ENTER to Update |
NOTE: The semicolon (;) is the tab character. You can set the tab positions merely by typing semicolons into the ruler line which is immediately above the first line of Cobol code. The default positions for the tabs are oriented to most Cobol programmers' preferences. You can adjust according to your own taste. To remove a tab position, just overtype the semicolon in the ruler line with any other character, such as a dot (.).
DO THIS: |
ALGNXT 600/JOIN/01-SIF/000 |
DO THIS: |
You will be immediately transferred to the MSKDEF screen.
TSKLST 600 PF8 = next page -- PF5 = Page 1 |
DO THIS: |
MSKDEF 600 Press PF10 to MSKCREAT |
DO THIS: |
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:
MSKDEF 600 Press PF10 to MSKCREAT |
DO THIS: |
You have selected the first variable for change.
MSKDEF 600 Press PF10 to MSKCREAT |
DO THIS: |
MSKDEF 600 -- HIT ENTER TO CHANGE -- |
DO THIS: |
NOTE:
MSKDEF 600 -- HIT ENTER TO CHANGE -- |
DO THIS: |
NOTE:
MSKDEF 600 ++ FIELD DATA CHANGED ++ |
DO THIS: |
DO THIS: |
DO THIS: |
DO THIS: |
DO THIS: |
NOTE:
VACSEE 01 |
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.
Project 1 is Done
Sample Project 2
DO THIS: |
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.
VACLOC 1 END OF LIST - PF5=Restart/PF7=Backward |
DO THIS: |
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: |
The indicated field's characteristics will appear in the pop-up window.
MSKDEF 600 Press PF10 to MSKCREAT |
DO THIS: |
The change will be recorded on the Dictionary and Mask 600 will be redisplayed to you ready for further action.
MSKDEF 600 -- HIT ENTER TO CHANGE -- |
DO THIS: |
MSKDEF 600 ++ FIELD DATA CHANGED ++ |
DO THIS: |
Your change will be recorded and Mask 600 will be redisplayed.
NOTE:
MSKDEF 600 -- HIT ENTER TO CHANGE -- |
DO THIS: |
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: |
You have cursor-selected it to change it. The update screen for STOTDUE will immediately appear.
SCDLST 600 END OF LIST - PF5=Restart/PF7=Backward |
DO THIS: |
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:
SCDCHG 600 /018/041 |
DO THIS: |
DO THIS: |
DO THIS: |
DO THIS: |
DO THIS: |
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.
VACLOC 1 END OF LIST - PF5=Restart/PF7=Backward |
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:
Default, Custom, and Proforma Code
Custom Code
Default Code
Logic of MMPCREAT at Insertion Points
ALGADD 600/EDIT |
ALGADD 600/REDKY |
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
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:
Named Proformas
The PF4 Key
customization code to be inserted into the program.
Your Own Proformas
-MAGECREP PRO mmmmmmmm/nnnnnnnn
-MAGECLST PRO mmmmmmmm/nnnnnnnn
-MAGECPUN PRO mmmmmmmm/nnnnnnnn
-MAGECPUN PRO
Modifiers & Page Numbers
ALG Key Structure
600/EDIT
600/EDIT/mmmmmmmm/ppp
600/EDIT/AMOUNTS/001
600/EDIT/AMOUNTS/002
600/EDIT/STATUS
Sample Project 3
DO THIS: |
The ALGADD screen will appear with the Proforma for the Insertion Point, %FUNCT.
DO THIS: |
You have added Custom code to the Library, it looks exactly like the Proforma so far. Next you will modify it.
ALGADD 600/FUNCT |
DO THIS: |
ALGNXT 600/FUNCT//000 |
DO THIS: |
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.
ALGADD 600/LOCINIT/VACTOT/1 |
DO THIS: |
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.
NOTE:
ALGADD 600/LOCINIT/VACTOT/1 |
DO THIS: |
The screen will be returned to you with the Function Code changed to ALGNXT, and with the existing Custom coding for %VARSTOR displayed.
ALGNXT 600/VARSTOR |
DO THIS: |
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:
ALGNXT 600/VARSTOR |
DO THIS: |
DO THIS: |
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.
ALGADD 600/SELECT/VACTOT/1 |
DO THIS: |
The ALGNXT screen will be returned showing your first page of coding.
ALGNXT 600/SELECT/VACTOT/1 |
Next, use ALGADD again to add page 2.
DO THIS: |
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: |
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:
NOTE:
ALGNXT 600/SELECT/VACTOT/2 Data ADDED to Database |
DO THIS: |
DO THIS: |
DO THIS: |
DO THIS: |
NOTE:
FCDSEE VACTOT
NOTE:
NOTE:
DO THIS: |
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.
VACTOT 000000000 END OF LIST - PF5=Restart/PF7=Backward |
DO THIS: |
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:
NOTE:
Helpful Hints
Solution to Test Project 4
IF (TWA-MSK-PF6-HIT)
MOVE QUOTE TO TWA-MSK-AID
MOVE FTH-FUNCT TO TWA-NONTP-REQUEST
MOVE 'SIFSEE' TO SFUNCT
GO TO AA900-GOBACK.
DO THIS: |
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: |
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: |
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.
VACSEE 01 |
DO THIS: |
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 THIS: |
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:
Required Data Not Entered
Warning! Bad Data on File
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:
Invalid State/Province Code
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.
DO THIS: |
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".
DO THIS: |
The SHDADD screen should appear with 800 set into the key area of the screen (SKEY).
DO THIS: |
NOTE:
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: |
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: |
The TSKLST display will appear showing your current status for developing MMP800.
DO THIS: |
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:
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: |
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:
DO THIS: |
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: |
DO THIS: |
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: |
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: |
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: |
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: |
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: |
IF (TWA-MSK-PF10-HIT) |
MOVE 'VAPSEE' TO SFUNCT |
GO TO AA760-ATTACH. |
DO THIS: |
The screen will return to you with your new lines of code inserted at the top.
DO THIS: |
Next you must re-compile MMP600 to include the new custom coding.
DO THIS: |
DO THIS: |
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: |
The familiar VACSEE screen should be displayed.
DO THIS: |
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: |
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.
Appendix A -- How to Call a SubTask
EXEC CICS LINK . . . 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:
MOVE 'nnn' TO TWA-NONTP-MMP.
PERFORM AA850-SUB-CALL THRU AA899-EXIT.
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:
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:
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:
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:
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:
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:
Appendix B -- How to Fetch Another Function
Chaining Screens
MOVE FTH-FUNCT TO TWA-NONTP-REQUEST.
MOVE 'xxxxxx' TO SFUNCT.
GO TO AA900-GOBACK.
transfer to.
MOVE FTH-CMD TO TWA-NONTP-REQUEST.
MOVE 'mmm' TO TWA-NONTP-MMP.
GO TO AA900-GOBACK.
Appendix C -- Reading a Mask
How to Initialize TWA-MSK-AREA
MOVE MSK-CMD TO TWA-TP-REQUEST.
MOVE 'NNN' TO TWA-TP-TRM.
PERFORM AA800-CALL-MONITOR THRU AA899-EXIT.
IF (GET-MSK-ERR)
PERFORM BB800-MSK-ERR-MSG THRU BB899-EXIT
GO TO AA800-SEND-SCREEN.
Mask Copybook
Appendix D -- Exit to Logo Screen
Fetching the Clear Screen
MOVE FTH-FUNCT TO TWA-NONTP-REQUEST.
MOVE CLEAR-FUNCT TO SFUNCT.
GO TO AA900-GOBACK.You must not GO TO AA900-GOBACK from within a PERFORM'ed routine.You can also fetch the Clear screen and specify a message to be shown in the SCOMPL screen field (top line, right half), code:
MOVE MSG-LIT TO TWA-TP-OP.
MOVE message TO TWA-MSK-AREA.
MOVE FTH-FUNCT TO TWA-NONTP-REQUEST.
MOVE CLEAR-FUNCT TO SFUNCT.
GO TO AA900-GOBACK.
Appendix E -- Setting Error Number
Editing
IF Sfield -----error condition---------
MOVE E TO SfieldE
MOVE 'nnn' TO ERROR-NUMBER
PERFORM CA100-LOAD-ERR-CODE-TBL THRU CA199-EXIT.
MAGEC ERR file.
IF Sfield -----error condition---------
MOVE E TO SfieldE
MOVE 'nnn' TO ERROR-NUMBER
PERFORM CA400-LOAD-WARNING-TO-TBL THRU CA499-EXIT.
Appendix F -- Defining Error Numbers
Adding & Updating to ERR File
Appendix G -- Coding for PF Keys
How to Test Which Key Was Hit
IF (TWA-MSK-PF1-HIT) .....
IF (TWA-MSK-ENTER-HIT) .....
IF (TWA-MSK-PF10-HIT) .....
- etc.
Simulating a Key
MOVE QUOTE TO TWA-MSK-AID.
Appendix H -- Insertion Points
Where to do Customization
Alphabetical List of Insertion Points
Appendix I -- Using SERRMSG & SCOMPL
Using Top and Bottom Rows of the Screen
MOVE work-area TO SERRMSG
MOVE message TO TWA-SERRMSG-MSG (n)
MOVE message TO SCOMPL
Appendix J --Transferring to non-MAGEC Programs
Why Transfer to non-MAGEC Program
From MAGEC to non-MAGEC
MOVE 'TRANSFER' TO TWA-NONTP-REQUEST.
MOVE 'tttt----dd...dd' TO SERRMSG.
GO TO AA900-GOBACK.
MOVE 'TRANSFER' TO TWA-NONTP-REQUEST.
MOVE 'ppppppppdd...dd' TO SERRMSG.
GO TO AA900-GOBACK.
01 DFHCOMMAREA. |
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:
SSSADD JOE JONES
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:
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:
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:
To convert from uppercase to lowercase, code:
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:
Note:
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:
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:
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:
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):
if it is a numeric field, code:
To validate (edit) the format of an input data field using the Pattern editing, code (usually in %EDIT):
To remove the pattern insertion characters from a patternized field, code (usually in %CALC):
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:
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:
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:
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:
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).
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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
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:
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.
Appendix K -- Data Transformations
Transform, Inspect, and Examine
Transform verb
TRANSFORM CUS01-NAME FROM LOWER-CASE TO UPPER-CASE.
CALL 'MAGXFRM' USING FORTY CUS01-NAME
TWENTY-SIX LOWER-CASE UPPER-CASE.
CALL 'UPCASE' USING FORTY CUS01-NAME.
CALL 'LOWCASE' USING FORTY CUS01-NAME.
Appendix L -- Reassigning Some PF Keys
PF2 - PF16 - PF17
PF16 Copy screen data to Copy/Paste Buffer
PF17 Paste data to screen from Copy/Paste Buffer
PF24 Pop-Up window for short list from prior browse
2. pressing ENTER (the proforma code on the screen gets added as Customization)
3. erasing the line saying: -MAGECINC PFKEYS/SAAMAGEC
4. inserting code to replace it
***** 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.
to simulate PF2
2
to simulate PF16
D
to simulate PF17
E
to simulate PF24
<
Assigning an Alternate Key
IF (TWA-MSK-PF23-HIT)
MOVE 'A' TO TWA-MSK-AID.
IF (TWA-MSK-PF13-HIT)
MOVE QUOTE TO TWA-MSK-AID.
IF (TWA-MSK-PF23-HIT)
MOVE 'A' TO TWA-MSK-AID.
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'
Appendix M -- Using Patterns for Fields
Displaying Field With Pattern
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.
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.
Editing Field Using Pattern
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.
De-Patternizing a Field
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.
Appendix N -- Altering the Key Delimiter
Delimiter Character
MOVE '-' TO D-LIMITER.
Appendix O -- Converting Dates
Date Conversion Subroutine
CALL 'MAGDATE' USING MAGEC-DATE-REQUEST-AREA.
IF (MAGDATE-OK) ...
Request Area
-MAGECINC DATRQ-C
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.
Validating a Date
Calling MAGDATE
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)...
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)...
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)...
Online Demo
Leap Years
Day-of-Week Codes
Appendix P -- Referencing Screen Fields
Screen Field Names
Sfield
the actual screen field
SfieldA
the 3270 attribute byte
SfieldE
the field's error flag
Sfield-POSN
the field's position on the screen
Sfield-N
numeric value of contents of Sfield
Sfield-ED
Cobol edit pattern for Sfield
Sfield-DAY-OF-WEEK
Sunday=1, Saturday=7, etc.
Sfield-JULIAN-DATE
Julian equivalent of entered date
Sfield-COLOR
color code
SfieldH
extended highlighting code
DEFAULT-COLOR
BLUE
RED
PINK
GREEN
TURQUOISE
YELLOW
WHITE
BLACK
NO-HILITE
UNDERLINE
BLINK
REVERSE-VIDEO
Symbolic Screen Field References
MOVE +10.00 TO @CUS01-AMOUNT@-N @CUS01-AMOUNT@-ED
MOVE RED TO @CUS01-AMOUNT@-COLOR
MOVE +10.00 TO SAMOUNT-N SAMOUNT-ED
MOVE RED TO SAMOUNT-COLOR
Appendix Q -- SQL
SQLCRE Function
SQLCRE nnn
%ADDIT
%DELET
%LOCKY
%REDNX
%RDUKY
%REDKY
%UPDAT
%RELES
%LITERAL
%SUBRTNM
600/ADDIT/MAGECSQL
600/REDKY/MAGECSQL
et cetera
eeeee-c/SQL
SQLPUR nnn
Appendix R -- Attach / Detach
Purpose for this Facilty
Design Criteria
Implementation and Use
*== This is often done in %PFKEYM or %PFKEYL
*== passing data via SERRMSG (optional)
IF ( you wish to attach to another function )
MOVE requested function TO SFUNCT
MOVE requested key TO SKEY
MOVE passed-information TO SERRMSG
GO TO AA760-ATTACH.
*== This is often done in %PFKEYM or %PFKEYL
*== passing data back via SERRMSG (optional)
IF ( you wish to detach )
MOVE return-information TO SERRMSG
GO TO AA770-DETACH.
05 TWA-SCOMPL-DATA.
07 TWA-SCOMPL-ATTDET PIC X(03)
07 TWA-SCOMPL-FUNCT PIC X(06)
07 TWA-SCOMPL-KEY PIC X(31)
*== This is often done in %PFKEYM or %PFKEYL
*== Determine if attached and, if so, detach
*== passing data back via SERRMSG (optional)
IF ( you wish to detach )
IF (TWA-SWAP-ATTACHED)
MOVE return-information TO SERRMSG
GO TO AA770-DETACH.
*== This is often done in %PFKEYM or %PFKEYL
*== Check to be sure that we can attach another level lower
IF ( something needs to be attached )
IF (NOT TWA-SWAP-LOWLEVEL)
do the attach logic .
*== Cancel the current Dialog programatically if required
IF (TWA-SWAP-DIALOG-A)
MOVE A TO TWA-SWAP-ID
ELSE
MOVE X TO TWA-SWAP-ID
*== This must be done in %PREINIT
*== Check for attach and utilize data passed in SERRMSG
IF (TWA-MSK-ATT-REQ)
IF (TWA-SCOMPL-ATTDET = 'ATT' ) AND
(TWA-SCOMPL-FUNCT is a valid function )
MOVE SERRMSG TO your-SERRMSG-work-area
continue as appropiate for attach
ELSE
take action for invalid attach .
*== This must be done in %PREINIT
*== Check for detach and utilize data passed in SERRMSG
IF (TWA-MSK-DET-REQ)
IF ( TWA-SCOMPL-ATTDET = 'DET' ) AND
( TWA-SCOMPL-FUNCT is a valid function )
MOVE SERRMSG TO your-SERRMSG-work-area
move various SERRMSG data to screen fields
GO TO AA800-SEND-SCREEN
ELSE
take action for invalid detach .
Appendix S -- Multi-Screen Applications
Screen Sequences
Two Approaches
First Approach
1. does not update the database
2. fetches to the second MMP, passing all the data captured and edited
3. lets the second MMP know that we are coming from the first MMP, with data passed
MOVE 'CS2' TO TEST-FUNCT-KEY.
MOVE TEST-FUNCT TO SFUNCT.
MOVE FTH-FUNCT TO TWA-NONTP-REQUEST.
GO TO AA900-GOBACK.
MOVE SFUNCT TO TEST-FUNCT
MOVE SKEY TO TEST-KEY
IF (TWA-LAST-KEY NOT = TEST-KEY)
OR (TEST-FUNCT-KEY NOT = 'CUS' AND 'CS2')
MOVE 'CUS' TO TEST-FUNCT-KEY
MOVE TEST-FUNCT TO SFUNCT
MOVE FTH-FUNCT TO TWA-NONTP-REQUEST
GO TO AA900-GOBACK.
****PERFORM AA840-CALL-MAGECIO THRU AA899-EXIT
Second Approach
MOVE 'CS2CHG' TO SFUNCT.
MOVE FTH-FUNCT TO TWA-NONTP-REQUEST.
GO TO AA900-GOBACK.
Toggling Between Screens
IF (SEE-FUNCTION)...
Sets of Masks
Appendix T -- Accessing Global Parms
Table #243
243ADD
243CHG
et cetera
-MAGECINC TBL01-C
MOVE '243' TO TBL01-TBL-NBR.
MOVE 'ERROR-HIGHLIGHT' TO TBL01-CODE-VALUE.
MOVE TBL01-KEY TO TWA-KEY-VALUE.
MOVE REDKY TO TWA-DB-CMD.
MOVE 'TBLK1' TO TWA-DB-FILE-NAME.
MOVE 'TBL01' TO TWA-ELT-LIST.
CALL 'MAGECSET' USING TWA-DB-AREA-A
TBL01-ELEMENT.
PERFORM AA840-CALL-MAGEC-IO THRU AA899-EXIT.
IF ( REC-FOUND )
MOVE TBL01-DESC TO some-work-field
ELSE
there is no ERROR-HIGHLIGHT specified (default will apply).
Appendix U -- List-type Update Screens
Multi-Record Updates
General Premises