This guide is written primarily for use by those persons who will be using the MAGEC software to develop and maintain online and batch applications.
Copies of this guide should be distributed to:
This book is not intended to replace the Online Documentation but to augment it. This book will introduce the reader to the basic process used to generate online applications. In order to demonstrate the tasks most effectively, it uses an actual new development project which the reader can do as he/she is following the tutorial instructions.
DO THIS: |
You may wish to go through the tutorial actually doing the project as you read, then re-read it for more complete explanation. This technique seems to facilitate faster learning for most people.
This manual depicts the development process for an online MMP (MAGEC Message Processer) using a text-based environment such as: a 3270 mainframe, MS-DOS, or text-mode Windows, Unix, or OS/2. In a graphical environment, such as GUI-mode WIndows, OS/2, or Unix, you can accomplish the exact same results using graphical panels which make MAGEC even easier to use.
Appendix K at the back of this section gives a brief description of the procedure you follow using MAGEC in GUI mode. There is an online tutorial which you can invoke from MAGEC which gives a detailed description with graphical illustrations of the development processes. To invoke the online tutorial:
The sample project we have chosen to demonstrate the application development process of MAGEC is the creation of a system which records vacation, sick leave, and comp time for your staff. Though this is a sample project, you may want to keep the new application you will create since it will be a complete, working system which you can use as is or may customize if you like.
The Vacation System we will create will use two "Data Classes" (files). They are:
You may wish to refer to Appendix A of this chapter to see more detailed information about these Data Classes. Both of them are already defined to your system and are ready to be used. If you wish to know more about the MAGEC processes used to define them you may refer to the "Database Administration" chapter of the Programmer's Reference Guide. You may also refer to the "Data Definition" chapter of this manual.
The VAC file will be the "primary data class" and the created application will do Inquiry, Update, Data Entry, Browse, and Programmerless Query functions against it. The SIF file will be accessed only to get the employee's name to display on the screen. It will not be updated. The key for the VAC data class is employee number, for the SIF it is a zero prefix plus employee number.
The application we will create consists of one Cobol program, called an MMP (MAGEC Message Processor). It will include nine online functions:
These are the standard set of nine functions which are produced automatically by MAGEC. Later you will see that through customization you can add your own additional functions with very little effort. All transactions in MAGEC are identified by a six-character function code like those listed above. The function code is always the first field on every screen, in the top left corner. It is immediately followed by a key value; hence, to see the data for employee #18, you could home the cursor to the upper left corner and type "VACSEE 18".
After you complete the exercise in this book you may wish to go on to the MAGEC "Customization" Tutorial, which uses the same Vacation System for its sample projects.
The VACLOC, VACSCN, and VACFND functions are called the "browse functions." The VACSCN and VACFND are also called "programmerless queries". All three of them can browse both forward and backward through the data and they all allow the operator to cursor select any item for either full-screen inquiry (VACSEE) or update (VACCHG).
In all cases the operator can enter the function code followed by an employee number (leading zeros not required) to do that particular function. The browses will accept a generic (inexact or partial) key. The application also will take advantage of the built-in automatic editing facilities of MAGEC to prevent bad data from being placed in the records.
The Vacation file and the Security Information file are already defined to the dictionary. The data items (fields) which make them up are also defined, including editing rules for each field. There is also a business rule defined for the Vacation data to specify that any employee number on the VAC file must first be defined to the SIF file. This will automatically generate code into your program to prevent a user from adding records to the VAC file for undefined employee numbers. This is just one example of the type of data integrity which can be enforced automatically using MAGEC's central dictionary and automated generation capabilities.
The data definitions for the VAC and SIF data classes take advantage of MAGEC's "Domain" facility. The data items (fields) which make up the keys for each file are defined as belonging to Domains. The employee numbers in each file are in the Domain called "EMPNUM", and the zero prefix for the key of the SIF file is in the Domain called "ZERO". This enables MAGEC to provide even greater automation for the development process than would be possible if Domains had not been specified; it enables MAGEC to fully automate the Logical Join process which will join the VAC data to the SIF data via the employee number. If Domains had not been specified, you could still develop the same application, but MAGEC would have to ask you to do a bit more work to properly join the SIF data to the VAC data.
The procedures to define Domains and to relate data items to them (as well as other data definition procedures) will be shown to you in the "Data Definition" chapter later in this manual. For now it is sufficient to note that the Domain facility will be employed in the development of this application, and that it enhances MAGEC's automated development capabilities.
If you are not the first person in your company to follow this tutorial to develop the sample application then you may need to delete the previous student's work in order to start fresh.
Follow the procedure in Appendix D of this chapter, if needed.
There are two principle components to any online application:
Before you can begin to create a new application you must first be assigned a Mask Number and an MMP Number for the application you are to develop. This is usually controlled by a central administrator to prevent two persons from trying to use the same numbers. For the purposes of this demonstration we have set aside one Mask Number and one MMP Number for your use. They are:
Assigning the same number for the MMP and Mask is not required by MAGEC but it does make them easy to remember. In some applications you may need to have multiple Masks for one MMP or multiple MMP's for one Mask. Either of these situations is fully supported by MAGEC. However, these cases are rare because of the many built-in capabilities and features of MAGEC, like automatic pop-up windows, browses and queries with cursor selection, window swapping, etc.
If you are curious you could refer to Appendix A now to review the VAC and SIF definitions. This is by no means necessary, but should satisfy your curiosity.
NOTE:
Hint:
GUI Development
The Sample Project
Vacation System
Getting Started
Deleting Previous Student's Work
Mask & MMP Numbers
DO THIS: |
If you receive the notification on the bottom line of the screen which tells you to press PF1 to read the broadcast message (MSGSEE), then do so at this time. This releases the bottom line of the screen for its normal uses.
Once you have logged on to MAGEC you are ready to start. There is a Task List function (TSKLST) built into MAGEC to assist you. It serves as both your developer's special menu and also as a status report to help you track your progress.
Every screen in MAGEC, including screens for your applications, follows certain standards. One of those standards is that the first field on every screen, at the top left corner, is a six-character function code field; immediately following it is a free-form key value field. You do not need to type the space which is always shown separating the function from the key since MAGEC inserts a 3270 attribute to cause the cursor to automatically skip to the key field.
There is a more complete discussion of the screen standards in the Programmer's Reference Guide, in the "Screen Painting" chapter. You may wish to read through later on to get a more thorough understanding. Definition of data files is shown in the "Data Definition" chapter of these tutorials.
NOTE:
To use the TSKLST:
DO THIS: |
TSKLST is entered into the screen function field and "600" is in the screen key field. "600" is the Mask Number you were assigned. The required first task which you must do will be to define your new application to the MAGEC Dictionary. This involves two entry screens: one for the screen header definition (for mask 600), and one for the MMP definition (for MMP600). The TSKLST will recognize that these have not yet been done and will immediately present the first screen.
DO THIS: |
Refer to Appendix J for a method to select Data Class and Elements from optional pop-up windows.
You are giving MAGEC the "name" (description) for your new screen and telling MAGEC that the primary data class is to be VAC and that you wish to use the element (record) named VAC01 from that data class. When you have entered all the data as shown, press ENTER. The screen header will be recorded and you will automatically be presented the next required definition screen, the MMP definition.
NOTE:
SHDADD 600 Enter data to be ADDED |
NOTE: If you did not know the Data Class or Element names you could press PF6 for a pop-up pick list to choose from.
DO THIS: |
If you made an error in either of these screens which the MAGEC software could not detect, such as misspelling your name, then you could return at any time to see or update these definitions just as you can for any other specifications in MAGEC. You would use:
When you have correctly completed this screen you will have defined your new MMP to the MAGEC Dictionary. If you made any errors you will have to correct them in order to continue.
After you correctly fill in this screen and press ENTER, you will see the TSKLST screen showing your current status.
MMPADD 600 Press ENTER to add information as shown |
DO THIS: |
The TSKLST will transfer you to the "mask definition" screen (MSKDEF).
NOTE:
TSKLST 600 PF8 = Next Page-- PF5 Key = Page 1 |
DO THIS: |
MSKDEF 600 |
DO THIS: |
JOIN01 600 |
DO THIS: |
It is possible to join to other Data Classes via either a Full-Key or Partial-Key read. The Full-Key read means that you will have a complete key value filled in and the generated logic will use a Read-by-Key-Exact (REDKY) command. The Partial-Key read means that you are only able to fill in the high-order portion(s) of the complete key and the generated logic will use Start-Browse-Read-Next logic (LOCKY, REDLE).
The generated logic will be stored as ordinary Cobol customization code which you can access and modify if you wish. After you have completed this entire tutorial project, you could review the generated code using the ALGLST (and related) functions online. The generated code will be in the %DATADEF and %JOIN insertion points.
The list of Elements shown on the Pick-List Screen will inlcude only those Elements which actually contain the keys for Data Classes to which you can automatically join. There may well be other Elements for each of the Data Classes represented. After you select one of the Elements from the Pick-List, MAGEC will present to you a list of other Elements associated with the one you selected. In this case, "associated with" means other Elements which are part of the same Data Class's record. You can select one or more of these associated Elements from that screen.
JOIN02 600 PF8=Page Forward : PF5=RESTART Browse |
DO THIS: |
JOIN03 600 PF8=Page Forward : PF5=RESTART Browse |
DO THIS: |
You might also notice that the counter which tells you how many more Elements may be selected has been decremented by one since you have joined one Element (SIF01). The fully-automated Logical Join process can generate code to join up to fifteen (15) Elements. You can do customization using Cobol to join additional data, if necessary. If you need to do customization to join more Elements, MAGEC's proforma facilities help to reduce coding and errors. You will learn more about proformas in the tutorials for Customization.
JOIN01 600 |
DO THIS: |