---<br />title: "app_main"<br />original_file: "app_main"<br />generated: "2026-06-12 10:24:05"<br />---<br /><br />**<br /># <br />Introduction ### Application Developer Tutoral<br />## <br />Who Should Read This Guide<br />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.<br />Copies of this guide should be distributed to:<br />Application Developers<br />Database Administrators<br />System Programmers<br />Auditors<br />This book is not intended to replace the Online Documentation but to augment it. This book will introduce the reader to (cont.)<br />the basic process used to generate online applications. In order to demonstrate the tasks most effectively, it uses an (cont.)<br />actual new development project which the reader can do as he/she is following the tutorial (cont.)<br />instructions.<br />## <br />Supplemental Reading<br />This guide is written assuming that the reader is familiar with the overall MAGEC philosophy. It presumes that you (cont.)<br />understand how the "standard set of nine" functions work and that you are familiar with the standard screen formats of (cont.)<br />MAGEC. You may wish to read through this book first to gain an initial understanding of the application development (cont.)<br />process. We suggest that you read the MAGEC *Application User's Guide* before actually designing and developing your (cont.)<br />own applications.<br />While doing the sample project it would also be useful for you to have several other chapters handy for reference:<br />"Database Administration"<br />"Security System"<br />"Offline Utilities"<br />"Librarian"<br />"Documentation"<br />"Analysis of the Generated MMP"<br />These are not required but will help you gain a more complete understanding of the MAGEC environment.<br />This tutorial may be used as an introductory course without requiring you to have read the other chapters listed above (cont.)<br />since brief explanations are included for all features necessary to develop and to test the sample (cont.)<br />application.<br />## <br />How to Use This Tutorial<br />Throughout this book you will find explicit commands telling you exactly what to do to develop the sample application. (cont.)<br />You will also notice quite a bit of explanation and background information to help you to understand what is (cont.)<br />happening.<br />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:<br />| ```<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;DO THIS:<br />The commands are inside a box like this.<br />&nbsp;&nbsp;&nbsp;<br />```** <br />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.<br />## <br />GUI Development<br />The PC Cobol versions of MAGEC are no longer available, they have been superseded by the LAMP Stack version. <br />[Read about the LAMP Stack version!](https://magec.com/images/MAGEC_RAD_PHP.pdf)<br /># <br />The Sample Project<br />## <br />Vacation System<br />The sample project we have chosen to demonstrate the application development process of MAGEC is the creation of a (cont.)<br />system which records vacation, sick leave, and comp time for your staff. Though this is a sample project, you may want (cont.)<br />to keep the new application you will create since it will be a complete, working system which you can use as is or may (cont.)<br />customize if you like.<br />The Vacation System we will create will use two "Data Classes" (files). They are:<br />1) VAC Vacation, Sick and Comp time Data<br />2) SIF Security Information File<br />You may wish to refer to Appendix A of this chapter to see more detailed information about these Data Classes. Both of (cont.)<br />them are already defined to your system and are ready to be used. If you wish to know more about the MAGEC processes (cont.)<br />used to define them you may refer to the "Database Administration" chapter of the *Programmer's Reference Guide*. You (cont.)<br />may also refer to the "Data Definition" chapter of this manual.<br />The VAC file will be the "primary data class" and the created application will do Inquiry, Update, Data Entry, Browse, (cont.)<br />and Programmerless Query functions against it. The SIF file will be accessed only to get the employee's name to display (cont.)<br />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 (cont.)<br />prefix plus employee number.<br />The application we will create consists of one Cobol program, called an MMP (MAGEC Message Processor). It will include nine online functions:<br />VACSEE Inquiry<br />VACCHG Update<br />VACDEL Delete<br />VACADD Add<br />VACNXT Inquiry, next employee (forward or backward)<br />VACDUP Duplicate existing record<br />VACLOC Simple browse with generic start<br />VACSCN Selective browse -- query by example<br />VACFND Complex search -- boolean search<br />These are the standard set of nine functions which are produced automatically by MAGEC. Later you will see that through (cont.)<br />customization you can add your own additional functions with very little effort. All transactions in MAGEC are (cont.)<br />identified by a six-character function code like those listed above. The function code is always the first field on (cont.)<br />every screen, in the top left corner. It is immediately followed by a key value; hence, to see the data for employee (cont.)<br />#18, you could home the cursor to the upper left corner and type "VACSEE 18".<br />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.<br />The VACLOC, VACSCN, and VACFND functions are called the "browse functions." The VACSCN and VACFND are also called (cont.)<br />"programmerless queries". All three of them can browse both forward and backward through the data and they all allow (cont.)<br />the operator to cursor select any item for either full-screen inquiry (VACSEE) or update (VACCHG).<br />In all cases the operator can enter the function code followed by an employee number (leading zeros not required) to do (cont.)<br />that particular function. The browses will accept a generic (inexact or partial) key. The application also will take (cont.)<br />advantage of the built-in automatic editing facilities of MAGEC to prevent bad data from being placed in the (cont.)<br />records.<br />The Vacation file and the Security Information file are already defined to the dictionary. The data items (fields) (cont.)<br />which make them up are also defined, including editing rules for each field. There is also a **business rule** defined (cont.)<br />for the Vacation data to specify that any employee number on the VAC file must first be defined to the SIF file. This (cont.)<br />will automatically generate code into your program to prevent a user from adding records to the VAC file for undefined (cont.)<br />employee numbers. This is just one example of the type of data integrity which can be enforced automatically using (cont.)<br />MAGEC's central dictionary and automated generation capabilities.<br />The data definitions for the VAC and SIF data classes take advantage of MAGEC's "Domain" facility. The data items (cont.)<br />(fields) which make up the keys for each file are defined as belonging to Domains. The employee numbers in each file (cont.)<br />are in the Domain called "EMPNUM", and the zero prefix for the key of the SIF file is in the Domain called "ZERO". This (cont.)<br />enables MAGEC to provide even greater automation for the development process than would be possible if Domains had not (cont.)<br />been specified; it enables MAGEC to fully automate the Logical Join process which will join the VAC data to the SIF (cont.)<br />data via the employee number. If Domains had not been specified, you could still develop the same application, but (cont.)<br />MAGEC would have to ask you to do a bit more work to properly join the SIF data to the VAC data.<br />The procedures to define Domains and to relate data items to them (as well as other data definition procedures) will be (cont.)<br />shown to you in the "Data Definition" chapter later in this manual. For now it is sufficient to note that the Domain (cont.)<br />facility will be employed in the development of this application, and that it enhances MAGEC's automated development (cont.)<br />capabilities.<br /># <br />Getting Started<br />## <br />Deleting Previous Student's Work<br />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.<br />Follow the procedure in Appendix D of this chapter, if needed.<br />## <br />Mask & MMP Numbers<br />There are two principle components to any online application:<br />Mask 3270 Screen Format and Editing Rules<br />MMP Online Cobol application program<br />Before you can begin to create a new application you must first be assigned a Mask Number and an MMP Number for the (cont.)<br />application you are to develop. This is usually controlled by a central administrator to prevent two persons from (cont.)<br />trying to use the same numbers. For the purposes of this demonstration we have set aside one Mask Number and one MMP (cont.)<br />Number for your use. They are:<br />Mask Number 600<br />MMP Number 600<br />Assigning the same number for the MMP and Mask is not required by MAGEC but it does make them easy to remember. In some (cont.)<br />applications you may need to have multiple Masks for one MMP or multiple MMP's for one Mask. Either of these situations (cont.)<br />is fully supported by MAGEC. However, these cases are rare because of the many built-in capabilities and features of (cont.)<br />MAGEC, like automatic pop-up windows, browses and queries with cursor selection, window swapping, (cont.)<br />etc.<br />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.<br />**<br />NOTE:<br />**<br />Mask and MMP numbers do not have to be numeric, they can be alphanumeric as well, following the pattern:<br />nxx<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<br />&nbsp;<br />where:<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<br />&nbsp;<br />n<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<br />= any digit (0 thru 9)<br />x<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<br />= any digit (0 thru 9) or any alphabetic character (A through Z, excluding space character)<br />Hence, some valid "numbers" are: 1AA, 12D, 8XY, etc. You should note as well that the numbers beginning with "6" are (cont.)<br />reserved for use by MAGEC Software and you should not use them for your applications.<br />**<br />Hint:<br />**<br />The appendices of this, and the other, tutorials often contain condensed information which is handy for reference by (cont.)<br />application developers, database adminsitrators, security officers, and the like. You may wish to copy some of them to (cont.)<br />keep them handy in condensed form as you are using MAGEC.<br /># <br />Task List<br />## <br />How to Begin<br />With the exception of the necessary offline (batch) Generate and Compile Job Streams, all of the development you do (cont.)<br />will be online through MAGEC screens. The first thing you must do is to "log on" to MAGEC. If you have not yet been (cont.)<br />defined to the MAGEC Security System and assigned a password, then now is the time to see your Security Officer to have (cont.)<br />that detail taken care of.<br />**<br />NOTE:<br />**<br />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.<br />| ```<br />**&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;DO THIS:<br />Log on to MAGEC.<br />&nbsp;&nbsp;&nbsp;<br />```** <br />If you receive the notification on the bottom line of the screen which tells you to press PF1 to read the broadcast (cont.)<br />message (MSGSEE), then do so at this time. This releases the bottom line of the screen for its normal uses. Refer to (cont.)<br />the ["PF Keys"](/DOC/magref_main.htm#MAGREF004001) reference table for a compact list.<br />Once you have logged on to MAGEC you are ready to start. There is a Task List function (TSKLST) built into MAGEC to (cont.)<br />assist you. It serves as both your developer's special menu and also as a status report to help you track your (cont.)<br />progress.<br />Every screen in MAGEC, including screens for your applications, follows certain standards. One of those standards is (cont.)<br />that the first field on every screen, at the top left corner, is a six-character function code field; immediately (cont.)<br />following it is a free-form key value field. You do not need to type the space which is always shown separating the (cont.)<br />function from the key since MAGEC inserts a 3270 attribute to cause the cursor to automatically skip to the key (cont.)<br />field.<br />There is a more complete discussion of the screen standards in the *Programmer's Reference Guide*, in the "Screen (cont.)<br />Painting" chapter. You may wish to read through later on to get a more thorough understanding. Definition of data files (cont.)<br />is shown in the "Data Definition" chapter of these tutorials.<br />**<br />NOTE:<br />**<br />The combination of a six-character function code plus a key value is often referred to as a "command".<br />To use the TSKLST:<br />| ```<br />**&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;DO THIS:<br />Type the command: TSKLST 600 on the top<br /><br />next: app02.md.txt