Introduction

---

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

Copies of this guide should be distributed to:

This book is not intended to replace the Online Documentation but to augment it. This book will introduce the reader to the basic process used to generate 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.

This guide is written assuming that the reader is familiar with the overall MAGEC philosophy. It presumes that you understand how the "standard set of nine" functions work and that you are familiar with the standard screen formats of MAGEC. You may wish to read through this book first to gain an initial understanding of the application development process. We suggest that you read the MAGEC Application User's Guide before actually designing and developing your own applications.

While doing the sample project it would also be useful for you to have several other chapters handy for reference:

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

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

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

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

DO THIS: The commands are inside a box like this.

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

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:

• Mask and MMP numbers do not have to be numeric, they can be alphanumeric as well, following the pattern:

• Hence, some valid "numbers" are: 1AA, 12D, 8XY, etc. You should note as well that the numbers beginning with "6" are reserved for use by MAGEC Software and you should not use them for your applications.

Hint:

• The appendices of this, and the other, tutorials often contain condensed information which is handy for reference by application developers, database adminsitrators, security officers, and the like. You may wish to copy some of them to keep them handy in condensed form as you are using MAGEC.

With the exception of the necessary offline (batch) Generate and Compile Job Streams, all of the development you do will be online through MAGEC screens. The first thing you must do is to "log on" to MAGEC. If you have not yet been defined to the MAGEC Security System and assigned a password, then now is the time to see your Security Officer to have that detail taken care of.

NOTE:

• A special logon identity is provided for your convenience in doing these tutorials, you can logon using an employee number of 18 and a password of ALEE.

DO THIS: Log on to MAGEC.

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:

• The combination of a six-character function code plus a key value is often referred to as a "command".

To use the TSKLST:

DO THIS: Type the command: TSKLST 600 on the top line of the screen and press ENTER.

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.

The Screen Header Definition screen is used to enter the definition for your mask. If you had not used the TSKLST then you could have entered the "command": SHDADD 600 to get here.

DO THIS: Fill in the screen exactly as it is shown on the facing page. Press ENTER.

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:

• The SHDDEL function deletes an existing screen header record, the SHDPUR function deletes it and all subordinate entities for the given application (SHD# given as the key).

Here you will define the new MMP you are going to create. You specify which mask it is to use, your name as the responsible programmer, and a description to be stored in the MAGEC Dictionary.

NOTE:

• This screen will be presented with all the necessary screen fields already filled in using default values taken from the Screen Header definition you have just completed. All you need to do is press ENTER in that case. If you wished to, you could overkey any of the specifications on the screen to modify them.

DO THIS: Press ENTER. (the default values are fine)

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.

The TSKLST screen shows what tasks can be done and which of them have been done at any given time. If your development is interrupted (by lunchtime perhaps) you can always see just where you left off and resume development from that point. The statuses are determined by the TSKLST by interrogating the actual dictionary data to see what has been recorded. The TSKLST is never out of date and needs no maintenance to remain current.

Notice the first two tasks are DONE. These were what you just completed on the prior two screens.

The second group of tasks (verifying the database definitions) is there for you to review the definitions which the database administrator recorded to define your primary data class (VAC). Notice that the first task (master key) is DONE. This means that the master (primary) key for that file has been defined. Notice that the second task (subordinate keys) is NOT DONE. That is because there are no other keys (alternate indexes) for this file. MAGEC fully supports up to nine keys per file automatically (and more with minor customization).

Since you have completed defining your new application to the MAGEC Dictionary it is time to proceed with the second step in the development process, Paint the Screen.

DO THIS: Use the arrow keys (up, down, left, right) to position the cursor down to the paint screen task (III. 1.), anywhere on the line will do, and press the ENTER key.

The TSKLST will transfer you to the "mask definition" screen (MSKDEF).

NOTE:

• If the tutorial project has been previously done by someone else, you may see a status of DONE shown for item III.4 (GENERATE MASK) on your TSKLST screen. This simply indicates that there is still a Mask initialization record on the dictionary for Mask 600. Do not be concerned. You will be overlaying that Mask record with your new one shortly. This situation is not an "error" even though it causes the TSKLST screen to appear slightly different from the one shown in this tutorial.

The MSKDEF screen can be used to "manually" paint your mask (the PF3 option) by drawing right onto the screen, or you can use the MAGEC Automated development features (the PF7 or PF8 options) to let MAGEC do the work for you.

If you manually paint your mask, you have total flexibility as to the appearance and format. If you use the automated development features then you must select from one of the format options which MAGEC can automatically generate. However, you can "have your cake and eat it too."

If you use the automated development features, MAGEC generates exactly the same dictionary definitions for the generated screen fields as you would if you manually painted the same screen. You can then use the MSKDEF manual screen painter to modify or add to what the automated feature created. You can also delete all of it in one command and tell the auto-paint feature to regenerate in a different format.

Regardless of which way you choose, you still have complete control over field attributes, extended color and highlighting attributes, database-to-screen field mapping, and data formatting.

There are two levels of automated development.

The semi-automated process (PF7 option) is interactive with the dictionary and generates all specifications with the exception of the logic to join (read) secondary files. The logic to read, update, browse, add to, and delete from the primary file (Vacation) will be automatically generated; only the logic to read additional files needs to be provided by you. Even in the semi-automated process, MAGEC generates most of that logic, leaving only a few lines of code for you to provide.

In the fully-automated process (PF8 option) MAGEC is able to generate all the code to join up-to fifteen (15) secondary files to your primary file. This process is driven by "Domain" definitions in the dictionary. You will learn more about Domains in the "Data Definition" tutorial. Using this process you are presented a list of candidate Data Classes (files) to which you can join; you select them by pointing with the cursor and pressing ENTER.

DO THIS: Press PF8 to select the fully automated processes.

The first screen in the fully-automated development process is the "side-by-side" Element Selection Screen. On the left half of the screen you will be displayed the list of Elements specified on the Screen Header as Elements from the primary Data Class to be accessed by this application. The right side of the screen will list joined Elements. To start with, there are not any joined Elements. If you wish to join Elements, you can press PF5.

DO THIS: Press PF5 to select Elements to be joined to the primary data.

The Element "Pick-List" Screen displays the names and descriptions of Elements which can be automatically joined. It determines which Elements can be joined by comparing the definitions for the keys of all Data Classes defined to the dictionary against the definitions of the Data Items which your application has already accessed as part of the primary, or other joined data. Data Items are matched based upon their Domain definitions.

That means that if there is a Data Class (say, a Part Master file named PMF) whose key consists of one field which is defined as belonging to the Domain "PARTNO", and your primary data (say, an Order file named ORD) contains a field which also belongs to that same Domain, MAGEC knows that it can use that field as a Foreign Key to access the PMF file's Elements. Then, after you have joined the PMF data, MAGEC knows that it can use any field within either the PMF data or the ORD data as a Foreign Key to access another Data Class. It can even combine (concatenate) fields to construct a compound key, if necessary.

DO THIS: Cursor-Select the SIF01 Element, press ENTER.

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.

The list of candidate Elements was made up of only Elements which contain the key fields for their Data Classes. It is possible that there are more Elements which are parts of the same Data Class. For example, there might be a Data Class for your Part Master File (PMF) which contains three Elements (PMF01, PMF02, and PMF03). Suppose that the primary key for PMF is within the PMF01 Element.

When the PMF's data is presented as a candidate for an automatic join, only the PMF01 Element will be listed. If you select it, you will next be shown the "Associated Elements Pick-List" showing you all of the PMF Elements. You can cursor-select any of them that you desire, and you can un-select any if you make a mistake--but you cannot un-select the PMF01 Element since it is the one which contains the key.

As you select Elements you will notice a status shown to the right. When you have selected as many as you wish, you should press PF6 to signal that you are done selecting.

When you press PF6, MAGEC will return to the Element Selection List screen. From there you may join additional data or you may signal MAGEC to generate the join code, record it into the dictionary as customization coding for the %JOIN and %DATADEF insertion points, and continue on to the screen definition processes.

DO THIS: Press PF6

You will be returned to the Element Selection List screen. Now it shows that you are joining one additional Element (SIF01) to your Primary data. If you wished to join more data you could press PF5 and you would be presented a list of candidate Elements again. Since MAGEC knows that you are already joining SIF01, it would be excluded from the list of candidates. It is possible, however, that the list might be longer than it was before you accomplished the join for SIF01. That is because it is possible that some of the data items within the SIF01 Element might be Foreign Keys into other files.

For this project we will not be joining any more data. PF6 signals that you are finished and tells MAGEC to generate the Cobol join coding and to store it in the dictionary as customization coding for your application (MMP600), and to proceed on to the screen definition processes.

DO THIS: Press PF6

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.

The next screen, PAINT2, will automatically be presented to you. On it you must select which data items (fields) you would like to have on your new mask, in the order in which you would like them shown (top to bottom, left to right). You use the cursor to "point to" the desired data items shown and use function keys to select or unselect them. ENTER selects, PF4 unselects.

The menu of data items shows all items from the elements selected on the PAINT1 screen in order. It may continue for multiple pages (screens), you can page forward by pressing PF8, or backwards by pressing PF7. If you reach the end you can press PF5 to start over at the beginning.

It is okay to select one or more items from the first page, then page forward to another page and select one or more from it, then return to the first page and select more items from it. As you select them you will see a flag ( ++ nn ++ ) showing which ones have been selected and in what order. You usually should select the most important "key" or "identifying" items first so they will appear at the top of the mask and browse screens.

If you realize that you have forgotten an Element which you should have specified not to worry! You can always hit the PF3 key to return to the prior screen without losing what you have done here on PAINT2. You may add additional Elements to the list or you may delete some, or both. If you delete an element for which you have selected some data items MAGEC will automatically unselect them for you.

DO THIS: Select the following items in the order shown:  (ENTER selects) from the first page: VAC01-EMPNUM 01 from the second page: (PF8 key pages forward) [see NOTES below] SIF01-FIRST-NAME 02 SIF01-LAST-NAME 03 again, from the first page: (PF7 key pages backward) VAC01-DATE-HIRED 04 VAC01-EARNED-VACATION 05 VAC01-TAKEN-VACATION 06 VAC01-EARNED-SICK-DAYS 07 VAC01-TAKEN-SICK DAYS 08 VAC01-EARNED-COMP-DAYS 09 VAC01-TAKEN-COMP-DAYS 10 VAC01-COMMENT 11 Press PF6 when you are done selecting.

If you make a mistake you can use PF4 to unselect an item, or you can use PF10 to unselect ALL the data items and start over. When you are through, press PF6 to invoke the automatic painter. It will present to you the Format Selection screen (PAINT3).

NOTES:

• VAC01-COMMENT occurs 3 times (arrayed field). This shows the first page of the menu of data items from which you may select. You can press PF8 to page forward, PF7 to page backward. If you select a group item using the ENTER key, you will be asked whether you wish to select it as one item (using PF19) or to select the elementary items below it individually (using PF18). The first and last names are just such group items, you should use PF19 for them.

The format selection screen is where you tell MAGEC which of the 7 possible formats to use to auto-paint your mask. You do so by positioning the cursor and pressing the ENTER key.

If you try to select a format which is not possible because of the number of data items you have selected then you will receive an error message and you will have to try another option.

Remember, if you select an option and then decide that you do not like the appearance of the generated mask, you can delete the mask and regenerate using another format option without having to reselect the data items. MAGEC has saved your selections and will "remember" them.

DO THIS: For this exercise choose option 2.

When you press the ENTER key to indicate which format is to be used, MAGEC will immediately begin to auto-paint your mask. If you had not specified any additional elements (on the PAINT1 screen) then you would be presented the MSKDEF screen showing the new mask format and allowing you to modify it if you desired.

NOTE:

• If you have used the fully-automated development processes to create the Logical Join code, there is no further work needed for the Join process and you will be transferred immediately to the MSKDEF screen painter. The remarks below apply only if you had not used the fully automated process, but rather, the semi-automated process.

If you are using the semi-automated development process; since you specified (on the PAINT1 screen) that you wanted the generated MMP to access the SIF data class (element SIF01) MAGEC will not immediately transfer you to MSKDEF, instead it will go into the "logical join" sequence to generate the necessary logic to "join" (read) that data. The SIF data class has only one key defined for it. If it had more than one key then MAGEC would present the PAINT5 screen for you to select which key is to be used to read it. Since there is only one key, MAGEC will automatically select that one and skip to the PAINT6 screen where you will tell it how to construct the key value argument to be used in the join logic.

NOTE:

• If you have used the fully-automated processes to generate your Logical Join code, this screen will not be presented to you. Please just turn to the next page in this tutorial.

The PAINT6 screen allows you to enter the logic to construct the key value used to read the joined data classes, in this case SIF.

On the screen you will see Cobol coding which is exactly what will be generated to accomplish the join. The Cobol code you see is identical to that which is shown in your MAGEC "Database Administration" chapter to access any type of file using the MAGEC I/O module.

The only part missing from the logic shown on the screen is the actual construction of the key value. MAGEC has no way of automatically knowing what key value you desire, so it allows you to enter whatever you wish here.

DO THIS: If you are using the fully-automated process, this screen does not appear--just turn to the next page in this book.

DO THIS: If you are using the semi-automated process, key in the two lines of Cobol code exactly like the code shown on the opposite page. Then press ENTER.

The key for the SIF data class consists of two component fields: a key prefix (2-byte binary), and employee number (4-byte binary, PIC S9(9)). You must key in two lines of Cobol code to fill in these two component fields.

If, for some reason, the resulting logic is not exactly what you need in special cases not to worry! You can modify or even entirely override this logic through normal MAGEC customization. The code generated by the automatic logical join is what has been determined to be the appropriate logic in most cases.

If you had specified more additional elements from other data classes (on the PAINT1 screen) then you would be stepped through the logical join sequence for each data class. The automatic logical join can handle up to fifteen (15) data classes (plus the one primary data class) for your one application (MMP). If you need to access more than fifteen additional elements, you can do so by using the normal MAGEC customization procedures which are slightly less "automatic", but are totally unlimited. You can, of course, let the automatic logical join handle the first 15 and just code your customization code for the remainder.

When you complete this screen you will be presented the MSKDEF screen with your new mask format displayed.

NOTE:

• You can bypass this process by just pressing PF10. This is useful in cases where you know that you will not want to keep the generated Join logic (as shown on the screen) since you will be replacing it with something else anyway (perhaps to acces a file using SQL or some other data language or CALL interface). It is also useful whan you are re-generating the screen format after having already done the necessary Join logic. It is not necessary to re-do the Join logic just because you might be re-generating the screen mask using a different format, or because you have selected a few more fields.

NOTE:

• This screen will not appear if you are using the fully-automated process; it will appear if you are using the semi-automated process. It is being shown here simply to familiarize you with it for those times you choose the semi-automated process instead of the fully-automated process.

The MSKDEF screen shows your newly "painted" mask. Remember, you could have accomplished exactly the same thing by manually painting the mask, though not as fast.

You can modify, add to, or even delete the entire mask definition here if you like. If you do not like the appearance of the mask and want to try another of the seven format options (remember PAINT3), you could enter the command (on top line of screen):

to delete the entire mask. The prompt screen asking which level of automation you would like to use to re-create this mask will appear. Then you could press PF8 , or PF7 to go into the auto-paint sequence again. MAGEC will have saved all the selections you made and will let you resume where you left off without having to re-select them. You may, of course, unselect any if you wish.

For this exercise we will make only a minor alteration to the generated mask. The first "variable field" on our new mask is the employee number (on line 4 of the screen). Variable fields are shown filled in with underscores ( __ ), or with the pattern which will be used to format and edit data into that field. In this case the employee number is shown with the pattern: 999-99-9999 . The employee number is the key for our VAC data class and the operator will enter it on the top line of the screen as a part of the "command". For instance:

It is not necessary, and would be confusing, for the operator to also enter the employee number into the variable field on line 4. We will solve that problem by altering the 3270 attribute for that field so as to make it a "protected" field rather than an "unprotected" field. That means that the operator will not be able to key into it and it will be a "display only" field.

DO THIS: Use the arrow keys to move the cursor down to the variable field on line 4 (after the literal "Emp#"). Anywhere in that field will be okay. On the at-sign (@) is also okay, but not on the greater-than symbol (>), which is used to show where that field ends. Press PF18.

You have selected that field for change, the bottom of the screen will now display the screen field characteristics from the MAGEC dictionary for that field. You can modify any of them.

NOTE:

• By positioning the cursor onto any displayed field and pressing a PF key you can modify, move, or delete that field.
  The instructions on the bottom lines indicate the meanings of the PF keys.
  You can draw new fields right onto this screen to add them.
  If you press PF1 (HELP) you will be displayed complete instructions for using MSKDEF.

• The "Screen Painting" chapter of your Programmer's Reference Guide offers detailed discussions for all MSKDEF operations.

The pop-up window shows the screen field characteristics for the employee number variable field you have selected.

The Cobol name for this field (in the mask copy book) is SEMPNUM. The symbolic 3270 attribute is UADRNF (unprotected, alphanumeric, display, regular intensity, non-selector pen, MDT off). You can refer to Appendix B of this chapter for more information about attributes, if you like.

You can also see that the edit type (refer to Appendix C) is "#" (numeric with a "pattern edit") and that it has 9 significant digits (left of decimal point), 0 decimal places and that it is an optional entry field (O) [as opposed to required (R)]. The contents of the field in the screen image reveals the pattern used to format this data to the screen (999-99-9999).

The database field which is the source for this screen field (on displays) and the target for it (on updates) is VAC01-EMPNUM. The position of this screen field is row 004, column 020 and it is 11 characters long on the screen. This field will appear on the browse screens (VACLOC, VACSCN, and VACFND) as the first data item (left to right) because of the LOC:1 we see in the bottom right corner of the pop-up window.

Now that we have reviewed the characteristics, let's proceed to make a simple modification.

DO THIS: Move the cursor to the attribute specification (UADRNF) and change it to SADRNF (skip-protect, alphanumeric, display, non- selector pen, MDT off). Press ENTER.

DO THIS: PF24 invokes a pop-up help screen which will list the 3270 color codes, attributes, and other useful information, the PF8 key pages forward through the pop-up help; to make the pop-up window disappear, press PF24 again. Try it, press PF24, then press PF24 again when you are done reading the help.

Your change will be recorded. If you press any key other than the ENTER key your change will be aborted and the dictionary definition will remain unchanged.

From the MSKDEF screen, PF10 invokes the MSKCREAT function, which produces both a Mask initialization record and a copybook defining the screen format for your MMP.

DO THIS: Press PF10 to invoke MSKCREAT.

DO THIS: PF12 is a universal return key from the MAGEC application developer functions, it returns to the TSKLST. Now, let's return to the TSKLST to see our status. Press PF12.

The MAGEC application development screens all recognize PF12 as meaning that you want to return to the TSKLST screen.

NOTE:

• If you are using MAGEC in a GUI environment, MAGEC will automatically generate a GUI panel for you the first time that you display a new Mask. When you press PF10 to invoke the MSKCRE function (which creates a new Mask), it automatically transfers to the MSKSEE function which displays the newly-generated Mask. In a GUI environment that will trigger MAGEC to begin creating a GUI panel for that Mask.

• MAGEC cannot create a GUI panel unless it is running in a GUI environment.

• If you do your development in a text environment, rather than a GUI environment, MAGEC will not generate the GUI panel for your Mask until the first time it is used in a GUI environment. That means that, unless you first execute your application (or, at least, do MSKSEE for its Mask) in a GUI environment, your end user may be the one to trigger the creation of the GUI panel. In that case, that end user will be asked various questions regarding the appearance of the new panel. For that reason, if your application is intended to be executed in GUI mode, you should probably make it a point to be the first GUI user of that screen so that you can make more informed choices regarding GUI options.

• Your end users will still have the option of setting individual color preferences to control the way GUI panels appear to them.; but you will have controlled which icons are included on the toolbar, the background panel color, et cetera.

• Refer to Appendix K at the back of this section for more information regarding generating a GUI panel.

MAGEC allows the Cobol-oriented developer to use his skills to the fullest. There is virtually no limit to how much customization you may do, nor to what you may do in your customization. However, customization is not required. The un-customized standard MMP which is generated is quite complete and ready to go.

For this exercise we will bypass Step 3 (Customization) and go on to Step 4 (Generate & Compile).

There is a series of tutorials involving various types of customization. If you proceed through this Tutorials manual to subsequent projects you will learn a great deal about customizing generated applications.

NOTE:

• The process we have you follow in these tutorials is intended to show you the process you should follow when developing you own applications. You should first enter specifications, just as you have done here, then generate the application without customization. After doing preliminary testing on the un-customized application you should begin adding customization, frequently re-generating and re-testing. This process is known as Self-Actualizing Prototyping since you have rapidly produced a prototype application and then iteratively improve it until it becomes the final, production-quality product.

The TSKLST screen now shows that you have accomplished quite a lot in so short a time.

There are 29 screen fields defined, which includes the headings and literals (prompts) and the screen variable fields. There were 11 variables corresponding to the 11 data items you selected in PAINT2, one of them OCCURS 3 TIMES.

The browse display will include 5 fields, the first five that you selected and in the order selected. The auto-paint feature includes the selected fields in the browse (locate) display, until it runs out of room on the 80-column display line used in the browses. You can override the selections made by auto-paint by simply updating the LOC: characteristics for screen fields (using MSKDEF, as previously shown).

All five of the fields to be included in the browse (locate) display have column headings specified for them. The auto-paint feature used the PROMPT (from the data item definitions) as the locate headings. If a given data item had not had a PROMPT specified it would have defaulted to the Cobol data name. All of ours had a PROMPT specified for this sample project.

You can also see that auto-paint has recorded some customization coding for your new application. This is the result of the automatic logical join. There is a data definition (%DATADEF) and, on a following page of the TSKLST, a logical join (%JOIN) recorded. The purpose for these particular pieces of customization code is to include a Cobol data definition for the SIF01 element into the MMP and to include the logical join coding to read the SIF01 element.

You are now ready to move on to the next step in the development process, generate and compile.

If you are using a mainframe computer:

DO THIS: Press PF15 to exit MAGEC. Enter your online job submission system (ICCF, ISPF, VOLLIE, etc.). Submit the MMPCREAT job stream for Mask 600 (specified in the MMPCRE control card). Check that there were no errors from the MMPCRE step or from the Cobol compile and link edit steps.

If you are using a PC:

DO THIS: Press Shift-F5 to exit MAGEC. At the DOS prompt type in the command: MMPCREAT 600. Allow it to execute. Check your results.

Depending on which TP monitor you are using you will have to use a different command to invoke the monitor's "new copy" routine. On a PC it is not necessary to do anything, MAGEC will automatically pick up the new copy if the program linked successfully. In CICS enter:

DO THIS: CEMT SET PR(MMP600) NEW (from CICS terminal) or: **CEMT SET PR(MMP600) NEW (from within MAGEC)

In Westi enter:

DO THIS: FCOPY,MMP600

These all accomplish (logically) the same thing. They notify your TP monitor that a new version of your program (MMP600) has been catalogued to the library.

Now, get back into MAGEC to begin testing. Use the TranID "TS01". We have pre-loaded some demonstration data onto the files for you to save time. You can use your new application to add your own data or to inquire, browse, query, update, add, or delete our demo data.

When your new program was being generated, MAGEC automatically generated test-only security parameters and added them to the dictionary for you. If your online (CICS or Westi) system has been "up" during that process, you will need to tell MAGEC to refresh its in-memory images of the security parameters from the dictionary in order to permit immediate testing of your new application. This is done via the **LOAD command.

DO THIS: In the upper-left corner of your screen (the function code field) enter: **LOAD, and press ENTER

DO THIS: Enter the command: VACSEE 01 on top line, press ENTER

The demonstration employee number 000000001 will be displayed to you. You might wish to alter the function code to VACCHG and update that record. You might also alter it to VACDEL to delete the record, and so on. If you just want to look at the demo data for now, you might wish to just press PF8 to "bump" forward to the next employee. Next, test the browse functions.

DO THIS: Enter the command: VACLOC 1 and press ENTER.

See what the browse screen looks like. Notice the column headings (locate headings).

Now try the cursor selection feature which is automatically provided with all MAGEC browses. Use the arrow keys to move the cursor down to one of the lines where an employee is listed (anywhere on the line will do). Press ENTER. You will immediately be transferred to the VACSEE screen for that employee. This feature lets you browse through the data without having to know the exact key value (employee #) and locate any item by visual recognition of, say, the name. That is why we call this a "locate" function.

The VACSCN and VACFND functions also support cursor selection. Try them now to see how they work.

DO THIS: Enter: VACSCN 1 on top line, press ENTER -- then key "harry" into the Selection Mask line (just below headings) under "First Name", press ENTER.

Then, if you would like some help press HELP PF1.

Every MAGEC function has built-in HELP-key support. MAGEC generates some basic online documentation for you when you generated your MMP (via MMPCREAT) earlier. You can add an unlimited amount of your own to supplement or replace it entirely.

Now try the "Find" function.

DO THIS: Enter: VACFND 1 on top line, press ENTER -- then key "harry|or|bob" into the Search Argument field, press ENTER.

Again, you may press HELP if you like.

Now, with a list of found employees shown on the VACFND screen, you can cursor-select one.

DO THIS: Point the cursor to a line on which an employee is displayed, press ENTER.

You will be shown the VACSEE screen for the selected employee.

If you wish to browse in descending order through the file (rather than ascending order) using any NXT, LOC, SCN, or FND function, you can do so pressing PF7

As you have already seen, every online function you generate with MAGEC has automatic HELP-key support and MAGEC even generates some basic online documentation for you.

MAGEC has a complete Online Documentation system built in. You may use it to enter and maintain whatever additional documentation you want to supplement or replace the standard instructions generated by MAGEC. You can even use the Online Documentation system to maintain documentation for non-MAGEC systems since it can also produce hardcopy manuals.

You may wish to refer to the "Documentation" chapter of your Programmer's Reference Guide for more information about the system. For this exercise we will bypass Step 6 (Documentation). In your real application development we strongly recommend that you not bypass it, though. Documentation is an important part of any application system.

The application you just created has several levels of online HELP built in. When the operator tries to enter invalid data into the screen and receives an error message, (s)he can press the PF1 key (F1 on a PC) to receive an error analysis HELP display.

When the user mis-enters the key (Employee number) and receives an "invalid key" message, (s)he can press PF1 to receive the key analysis display.

If the user hasn't made either of the above mistakes, but just wishes to get HELP for the function (s)he is trying to do; (s)he can just press the PF1 key and the function-level HELP display will be presented.

If the user wishes to see documentation for a given field on the screen, (s)he can point the cursor to that field and press PF2 and a field-level HELP display will be presented.

All these features are generated automatically into every online application. Basic HELP text is also automatically created for you -- you can add your own text, as well.

DO THIS: On the VACSEE screen, press the HELP key PF1.

You will receive the Function-Level HELP screen.

DO THIS: Press PF8 to browse forward   Press PF3 to return to your VACSEE screen.

Next, let's see the field-level HELP facility.

DO THIS: Point to the hire date field, press the Field-Level HELP key, PF2.

When you generated your new MMP (via MMPCREAT) MAGEC automatically created safe, test-only security profiles for each of the nine new online functions (VACADD, VACSEE, etc.). This allowed you to immediately test and demonstrate your new application without having to manually define each function to the security system. These automatically generated security parameters do not permit "production" use of the new application.

When you have completed the testing and revising of your new application and are ready for it to "go into production", you merely need to alter the security parameters to indicate that the new functions are now allowed for use in "production". Actually, in some shops this task is handled by designated security officers. The parameters are entered or modified online and are stored in the MAGEC Dictionary. You do not need to wait for any assemblies, table updates, or interruptions to online processing. Changes can be made effective immediately.

For more detailed information regarding the tasks of the security officers refer to the MAGEC "Security" chapter.

In completing the tutorial for this first project you have produced a powerful and useful online application. We encourage you to fully exercise and test the new Vacation system you have just created in order to understand just how much you can accomplish in so short a time with MAGEC.

Your new application supports Inquiry, Update, Data Entry, Browse, and Programmerless Query. The data is always properly edited and formatted for you. Entry formats are extremely user-friendly and "bad data" never reaches the files.

The nine standard functions were generated automatically for you and they are all done in one compact, efficient program. The program easily handles multiple files and multiple screens.

All access to these new functions and the vacation data are governed by the built-in security system. You (or your security officer) can control When, Where, and by Whom each function can be done. Changes to security parameters take effect immediately.

MAGEC will automatically create custom menus for your users based upon their individual security authorizations. You never need to do any programming or maintenence for these menus.

The new application automatically has Pop-Up Windows and Window swapping features. The user can have two full-screen sessions active at one terminal, (s)he can swap between them using the PF9 key. The user can also cursor-select an item from a browse or query screen and then, by pressing PF24, receive a pop-up list of the ID's of all the items shown on that browse or query--cursor-selecting from that pop-up list will transfer to the selected item.

Each function of the new application has HELP key support. By simply pressing PF1 the user can view Online Documentation for the function (s)he is doing, or for any error messages, without disturbing the screen or data being displayed. Field-level HELP is accommodated via PF2 (F2 on PC). If a screen field is being validated using MAGEC's table lookup facility, then the field-level help display will include a scrolling display (a "pick list") of valid entries with descriptions cursor-selecting from that scrolling list will automatically fill the original screen field with the selected value.

Copy and Paste facilities are accommodated using PF16 (Copy) and PF17 (Paste). This enables your user to copy data from any field of any screen to any other without re-keying it.

The new application is extremely efficient. It even compresses messages to minimize transmissions both to and from the terminal.

You can print hardcopy technical documentation for the new application by executing the MSKDOC batch utility program. You can also print the standard Cobol compile listing.

You have unlimited customization capabilities, there is virtually nothing that you cannot do using MAGEC. What you have demonstrated so far is merely what MAGEC generates without any customization. This is what might be called a "vanilla" application in MAGEC. In the MAGEC "Customization" Tutorial you will learn how to modify this vanilla application using standard Cobol coding which MAGEC will save in its dictionary and insert into the source program.

The VAC data class is defined as a VSAM/KSDS file with a DD NAME of TSTK1. The total record length is 270 bytes. There are two elements defined:

There is one key for the VAC data class:

The VAC data class is actually a redefinition of the MAGEC "test" file (TSTK1). There is also a data class named TST which defines this same file. That is the reason for the 9-byte padding on the key.

The Cobol copy book defining the VAC01 element is on the MAGEC library (ALG-file) as a member named VAC01-C. You may review it online in MAGEC by entering:

To view the data class definition for VAC enter:

To view the key definition enter:

To view the element defintions enter:

To view the data item (field) definitions for VAC01 enter:

You can cursor-select any item to see more detail.

The SIF data class is defined as a VSAM/KSDS file with a DD NAME of SIFK1. The total record length is 300 bytes. There are two elements defined:

There is one key for the SIF data class:

The Cobol copy book defining the SIF01 element is on the MAGEC library (ALG-file) as a member named SIF01-C. You may review it online in MAGEC by entering:

To view the data class definition for SIF enter:

To view the key definition enter:

To view the element definitions enter:

To view the data item (field) definitions for SIF01 enter:

(you can cursor-select any item to see more detail)

NOTE:

• There is a security authorization requirement to access the SIF01 element. Also, some of its data is encrypted for further security.

The standard default logic generated by MAGEC handles attributes so well that you will rarely need to deal with them. However, MAGEC allows you to freely manipulate 3270 attributes both at execution time and as you are "painting" your screens. You can easily override the default attributes.

To simplify your work in handling 3270 attributes we have established a naming scheme for them. Your online programs (MMP's) include a copy book which equates these mnemonics to the actual one-byte attribute codes. You can view that copy book in MAGEC by entering:

The symbolic names for the attribute codes are six-charaters long, each character position having a specific meaning and set of possible values:

NOTE:

• In a GUI environment the distinction between the Protect and Skip-Protect attributes is somewhat more important than in a text-based environemnt. If your application is executing in text mode, then the only difference between these attributes is that as the operator is typing into the screen the cursor will automatically skip, upon reaching a Skip-protect attribute on the screen, to the next Unprotected field. This is compared to the cursor simply stopping upon reaching a Protect attribute.

• In GUI mode, the operator cannot even place the cursor to any Skip-Protected field on the screen. This is true whether using a mouse or cursor movement keys on the keyboard. That means that if your application expects the operator to point to a certain position or field on the screen, it must not be Skip-Protected.

In the MAGEC003 copy book included in your MMP's the symbolic six-character name is prefixed with an "AT" so that they will all appear together in a sorted cross reference listing (if used) from the Cobol compiler.

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

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

There are three general categories of edit types:

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

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

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

NOTE:

• When the operator enters data into screen fields MAGEC accepts any valid, unambiguous format depending upon the edit type. For instance, in a type-$ field the operator may enter:

If you are not the first one to follow the tutorial exercise then you will need to delete the previous student's work so that you can start "from scratch". You must be logged on to MAGEC before doing the procedure below.

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

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

MAGEC includes a variety of utilities and features to assist you in resolving problems you might encounter in the course of using MAGEC either to develop applications or in the execution of those applications. You could save many hours of frustrating work by familiarizing yourself with them. This appendix is a brief summary of many of the most useful aids and techniques.

If you would like complete hardcopy documentation, including where-used reporting for any given data-class, you can execute the batch DCLDOC utility. Refer to the "Offline Utilities" chapter of your Programmer's Reference Guide for control card and execution instructions.

If you would like to see or update the contents of a file, you can use the online DBDITO function which provides combined character/hexadecimal display and update capabilities. Refer to the "Database Administration" chapter of your Programmer's Reference Guide.

If you are using a PC and would like a hardcopy dump of your file, use the MAGUNLD utility provided with MAGEC for PC's. Refer to the MAGEC Installation Guide for information regarding MAGUNLD.

On a mainframe you can use the (IBM) IDCAMS utility to produce a file dump for VSAM files.

If you would like hardcopy documentation of all the specifications for your application, execute the batch msk documentation utility, MSKDOC. Refer to the "Offline Utilities" chapter of the Programmer's Reference Guide for control card and execution instructions.

If you are using a PC, you can invoke your program in trace mode by executing MAGEC's TRACE.BAT file instead of the TS01.BAT file. The trace utilizes Realia COBOL's RealDBUG utility. It includes online instructions for key utilization. You can also refer to you Realia documentation for more specifics on the use of RealDBUG.

where tttt is the desired terminal ID. Omitting the tttt will purge the TWA records for all terminals except the one you are at. Be sure noone is trying to access MAGEC from any terminal for which you are purging records.

You can purge all records from the TWA file by executing (in batch, while online MAGEC is not running) a DELETE/DEFINE IDCAMS job, then MAGINIT to initialize the file.

In the event that you wish to see the actual Cobol source code generated by MAGEC, you have several means available to you.

If you are running on a PC using PC MAGEC with Realia Cobol you can interactively trace your MMP by invoking MAGEC using the TRACE command (.BAT file) instead of the TS01 command. This executes the REALDBUG debugger with MAGEC executing "under" it. You can then enter your application's function code. If you have the .LST, .SYM, and .MAP files (created by the compiler) in your \MAGEC directory, the debugger will display your Cobol code as it executes. You can set breakpoints, stop and start execution, single step forward, view the contents of data fields, and alter their contents, if you wish.

On the PC you can also print the compiler listing using the command:

Where nnn is your MMP number, and LPT1: is the port to which your printer is attached.

Instead of the .LST file, you could also print or view the .COB file, which is the actual input to the Cobol compiler. Of course, you can view these files on your monitor using any available editor or the DOS TYPE command (piped to MORE, if desired), ie:

On the mainframe you can view the Cobol listing using your online editor to access the POWER or JES (or other) queue. You can also route it to the printer just as for any other compile listing.

If you are fortunate enough to have a Cobol debugger on your mainframe (ie: EZtest, Intertest, etc.) you can utilize it with your MAGEC MMP's, as well.

MODELWIN is a version 2.6 feature of MAGEC that allows you to create fully-functional pop-up window maintenance applications. These pop-ups are useful for updating records while not having to leave the full-screen application you're working in. They can contain any or all of the standard set of nine functions, but in a miniature one-fourth size screen.

In order to specify an MMP as a pop-up window application:

Any fields painted outside of the border will cause a warning message to display in SCOMPL:

This warning will not, however, keep the field from being added to the mask. Any field painted entirely inside or entirely outside of the window border will be part of the mask. Any fields drawn overlapping the borders will cause the "overlapping fields" error message to be displayed.

The field names for the borders are: SBTOP, SBBOTOM, SBRIGHT, and SBLEFT. If these screen names are altered your program will not compile properly. The Cobol code generated when you use MODELWIN makes reference to all these border fields in order to adjust them for monochrome or color terminals.

When you are filling in the specifications for the SHD (Screen Header) definition, you are asked to give the Data Class (DCL) name (i.e. VAC) and the Element (ELT) names for the data Elements (i.e. VAC01, VAC02, etc.) You could, if you knew them, just type in the 3-character Data Class name and the 5-character Element names. This was how you did it in the tutorial project; but what if you did not remember the names or their correct spellings?

MAGEC provides for you to request a pop-up window to help you search for the proper Data Class and Elements knowing only a fragment of the description. For example, you might not remember that the DCL name for the vacation data file was VAC, but only that its description contains the word "vacation". You might not remember the Element names of the Elements which contain the employee address and vacation data.

By pressing PF6 from the SHD definition screen you can request the pop-up data selection windows.

First, you will be asked to enter a search argument to search for the Data Class. If you leave the argument blank, you will be listed all Data Classes defined to MAGEC. If you enter a character string, only those Data Classes containing that character string will be shown. This pop-up is actually a standard MAGEC FND function (query) against the DCL definitions from the repository. You can scroll up and down through the list if more than one page of items matches the selection argument. To select the desired Data Class, place the cursor to the line on which it is shown and press ENTER. To abandon the search, press PF3.

Next, after making the DCL selection, you will be presented a list of all the Elements which make up the chosen Data Class. You can scroll up and down through this list also, if it spans more than one page. You can select an Element by pointing the cursor to the line on which it is displayed and pressing ENTER. The selected items will apear highlighted using reverse video, if your terminal or monitor supports reverse video. You can select up to nine Elements. When you are done, press PF6 to pass both the DCL and ELT selections back to the SHD screen. To abandon the selections, press PF3.

PF3 will return you to the SHD screen with no changes; no selections passed back to it. PF6 will record your selections. If all of the other specification on the SHDADD screen are acceptable (there are no errors found in the validation of what you have entered), you will likely be transferred immediately to the MMPADD screen without again seeing the SHDADD screen, this is normal. It helps expedite the definitions for a new application.

You can return to the SHD definition screen at any time by selecting it from the TSKLST, or by typing in the command: SHDSEE xxx (where xxx is your Screen Header number, "600" in the example project used in this tutorial)

You can press PF6 from the SHD screen while you are displaying the existing definitions. The same pop-up windows will apprear. Since you may wish to retain some or all of the selections you originally made, they will be shown (remembered) when the pop-up windows appear. You can override them easily. Pointing to a selected ELT and pressing PF4 will un-select it. There are PF key instructions displayed in SERRMSG (last three lines of the screen), as with all MAGEC functions.

The first window allows you to search for a Data Class using any string of characters which might appear in the 3-character DCL name or in the description. You can select the one you want by pointing with the cursor and pressing ENTER.

When you make your selection from the first window you will automatically be presented the second window.

The second window lists the Elements which make up the selected Data Class. You can select one or more Elements by pointing with the cursor and pressing ENTER. PF4 will un-select a selected Element. PF6 will pass your selections back to the SHD screen.

You can select multiple Elements. The ones you select will be highlighted if you are at a monitor or terminal which supports reverse video.

MAGEC-generated applications can be executed in either text (character) mode or in GUI (Graphical User Interface) mode. You do not have to do any special development tasks in order to generate GUI applications; in fact, the same program can be executed in text mode and in GUI mode without even being re-compiled.

The way MAGEC handles this is by automatically generating a GUI "panel" for your application if a user executes it in a GUI environment and no panel already exists. A GUI panel is simply a definition of the screen, including its menu bar, pull-down menus, and toolbar icons. MAGEC is unique in its ability to automatically generate a GUI panel from your text-based application. This is possible only because MAGEC applications automatically, in text mode or in GUI mode, include features which are normally found only in GUI applications. The GUI panel is merely a different presentation of the same program functions and data. It has a more appealing look and takes advantage of the mouse better than a text display does.

If you develop your application in a GUI environment you will be the first person to use the new screen and therefore you will cause the GUI panel to be generated. This happens when you generate the mask by pressing PF10 from the MSKDEF screen. When the mask is generated it is then displayed to you using the MSKSEE function, if no GUI panel exists for this mask MAGEC immediately generates it at that time. If you develop your application in text mode it is possible that one of your users might be the first person to use it in GUI mode and he/she will therefore cause the GUI panel to be generated. This could be important since MAGEC will ask various questions of the operator (either you or your user) to choose from a number of options regarding screen appearance and toolbar icons. You may (!) prefer to be the one to make those choices.

Once the GUI panel has been generated you can use the GUI screen painter to customize it if you so desire. That is not necessary, but it does allow you to dress up your panel with some of your own graphics, et cetera..

Now lets discuss the options you will be asked to choose from when the GUI panel is being generated

You can create an application in either text or GUI mode. Regardless which mode you used to do the development, the application can be executed in both text and GUI mode. If you do the development in GUI mode, however, MAGEC helps you even more by providing very user-friendly panels instead of the text screens. It also allows you to access the GUI screen painter to make further customization changes to your GUI panel.

You may wish to refer to the discussion in you Programmer's Reference Manual, Screen Painting section, under the topic "GUITOOL". It describes a related facility which enables you to dynamically create GUI objects from your MMP. The principles for GUITOOL and for the GUI screen painter are the same.

A detailed discussion, with graphical exhibits, can be accessed online from MAGEC (in GUI mode). To access it: from the menu bar at the top of any MAGEC screen, select Help, then select Tutorial.

To do development in GUI mode you can actually use the same text screens as you used in text mode, but that would not take advantage of the power of a graphical environment. Rather, you should enter the special GUI development process by selecting the "Develop" icon from either the MAGEC logo screen (clear screen), or from the logon screen. These icons appear only if you are authorized to do development via the MAGEC security system.

After you have selected the Develop icon, MAGEC presents a small pop-up asking whether you wish to do development of an online MMP, a batch MBP, or data definitions. If you select online MMP MAGEC then presents another pop-up listing the major tasks involved in developing an MMP.

The first task is to define the application profile. In text mode that consists of the SHD and MMP header screens and their various associated pop-up windows. In GUI, all of that is contained on one Application Profile panel.

After you have filled in the profile you return to the major task list which offers the categories: Profile, Screen Painting, GUI, Cobol Customization, and Documentation. You would next select "Screen Painting" which includes automatic logical join data selection with field selection and screen generation. This is functionally very similar to what you did in text mode, but using much more friendly panels.

Next you would select "GUI", which takes you to the GUI screen painter. The GUI screen painter does not start with a blank slate, rather, it starts with the screen that was generated in the basic text mask generation, with the toolbar as it was defined. In the GUI screen painter you can make further modifications to the panel. They might include adding pushbuttons or bitmap icons, modifying the toolbar, or changing some ordinary text fields into list boxes, combo boxes, radio buttons, et cetera.

Whereas your text mask is saved on MAGEC's Mask file to be retrieved by the MMP when it executes, the GUI panel is saved on another file, called MSKPAN.UIB. When you make changes to the panel using the GUI screen painter, you will save the modified panel to the file to retain your changes.

The types of changes you can make to a panel are limited. That is because MAGEC retains the portability of your MMP--it will always work correctly in both GUI and text modes. Your MMP communicates with the screen via the text Mask that you created. In GUI-mode execution, MAGEC maps the data from the text Mask to the GUI panel. That means that you cannot add a new text field to the GUI panel which does not exist on the text Mask, since there would be nowhere for MAGEC to pass the data from that field into your MMP. You can add non-entry fields (called static fields) or pushbuttons and icons which pass only a PF key to the MMP. You can also convert plain text fields into more helpful GUI structures which reduce both typing and entry errors.

In text mode you use the ALGADD (etc.) functions to add or modify Cobol customization coding to your application. In order to do this you must know the names of the Customization Insertion points where you want the code to be inserted. You can use the printed Programmer's Reference book to look up Insertion Point names and descriptions. In GUI mode a much easier method is available.

When you select "Customization" from the task list panel, MAGEC then presents another panel asking you for which function you wish to do customization. The choices include all the standard MAGEC functions.

When you select a function, MAGEC presents a diagram of the logic for that function, similar to the diagrams found in your Programmer's Reference manual. You can see the Insertion Points in their proper places in the logic flow of the MMP, and you can mouse-select them to see the same descriptions as are available in the manual, or to add/modify Cobol Customization.

Rather than use MAGEC's ALGxxx functions, you can use any text editor product (i.e.: SPF/PC, WRITE, etc.) you prefer. MAGEC automatically passes the Cobol Customization code to the editor you specify in you settings and invokes that editor. When you finish making your changes, MAGEC saves them on the ALG file for you.