Who Should Read This Guide

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:

  • Application Developers
  • Database Administrators
  • System Programmers
  • Auditors
  • 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.

    Supplemental Reading

    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:

  • "Database Administration"
  • "Security System"
  • "Offline Utilities"
  • "Librarian"
  • "Documentation"
  • "Analysis of the Generated MMP"
  • 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.

    How to Use This Tutorial

    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.

    GUI Development

    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:

    select Help from the menu bar at the top of your display screen

    select Tutorial.

    The Sample Project

    Vacation System

    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:

    1) VAC Vacation, Sick and Comp time Data

    2) SIF Security Information File

    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:

    VACSEE Inquiry

    VACCHG Update

    VACDEL Delete

    VACADD Add

    VACNXT Inquiry, next employee (forward or backward)

    VACDUP Duplicate existing record

    VACLOC Simple browse with generic start

    VACSCN Selective browse -- query by example

    VACFND Complex search -- boolean search

    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.

    Getting Started

    Deleting Previous Student's Work

    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.

    Mask & MMP Numbers

    There are two principle components to any online application:

    Mask 3270 Screen Format and Editing Rules

    MMP Online Cobol application program

    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:

    Mask Number 600

    MMP Number 600

    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.




    n               = any digit (0 thru 9)

    x               = any digit (0 thru 9) or any alphabetic character (A through Z, excluding space character)


    Task List

    How to Begin

    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.


         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.


    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.

    STEP 1 --  Define Application


    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.

    Description will be used as a heading for the generated screen later in the process.

    MMP# will be 600 for this example, identifies the program to be generated.

    Function Code Prefix is the 3-character prefix to be used in the generated application's function codes. Default is the 3-character Data Class (DCL).

    Use Model specifies the model to be used when defining the MMP. Valid entries are MODELMMP or MODELWIN or other valid model names defined on MAGEC Lookup Table #205. Set to MODELMMP, which is the default.

    Verify Opt (VERIFY or NO) specifies whether or not MAGEC is to generate code into the MMP to protect against bad data coming in from the files by doing an IF NUMERIC test on all numeric data items before trying to access them. Specifying VERIFY here will prevent "Data Exception" type errors caused by garbage in your records.

    Extd. Color system fields allows you to specify whether you wish the standard MAGEC fields which are on every screen to have 7-color attribute controls.

    Color protected fields and Color unprotected fields are the designations for default colors to be used for fields on the generated screen. You can override these, field-by-field, if you wish. If you leave these specifications blank (or if you enter "0" into them) then no extended color support will be generated. If you enter a color code (1 through 7), the specified color will be used for each class of screen fields generated. The color codes are: 1 = blue, 2 = red, 3 = pink, 4 = green, 5 = turquoise, 6 = yellow, 7 = white or black.

    DCL is the 3-character name of the Primary Data Class (file) for this application.

    ELT 1 thru ELT 9 are the 5-character names of the elements (record segments) desired.

    Programmer is the name of the person responsible for this you!

    Last Generated and Last Updated are posted to by MAGEC automatically when you generate and compile your application. This is useful for inquiry purposes and is also used by MAGEC's automatic version verification process.


     SHDADD 600                             Enter data to be ADDED
    M A G E C Data Dictionary
    Screen Header Definition for MSK 600

    Description: vacation/sick/comp days
    MMP#: 600 Function Code Prefix:   Use Model:  MODELMMP  Verify Opt: no ______ 'VERIFY' or 'NO'
    Extd. Color system fields: n Y OR N 
      Color protected fields: _ (no color) 
    Color unprotected fields: _ (no color)

    P R I M A R Y  D A T A 
    DCL: vac
    ELTs: ..1.. ..2.. ..3.. ..4.. ..5.. ..6.. ..7.. ..8.. ..9..
    vac01  ____  ____  ____  ____  ____  ____  ____  ____
    Press PF6 to select a Data Class and Elements 

    Programmer: YOUR NAME Last Generated:  Last Updated: 


    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.

    Figure 01 -- Screen Header Definition


    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.


         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:

    SHDCHG 600               for the Screen Header

    MMPCHG 600               for the MMP Header

    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.

    MMP# will be filled in by MAGEC.

    MMP Description is a 30-character description for identification in dictionary lists, etc.

    Mask Number is the number of the mask which this program will use. You are not actually limited to one mask per program, if you access more than one then this would be the main one (first one).

    Programmer is the name of the person responsible.

    Date Generated and Time Generated on both the MMP and the SHD definition screens are posted to by MAGEC automatically when you generate and compile your application. You can always refer to these screens to determine when the application was last generated/compiled. You can compare that to the date it was last modified from a dictionary index report. These dates are also used in the automatic version verification online function built into MAGEC.

    Abend Handler (CICS ONLY) is the 8-character name (7-character for VSE) of a program which you wish to handle program abends. If you leave this blank then CICS will issue the ordinary ASRA, or other, abend code and will abort your task when a data exception or other program error occurs. If you specify a name (non-blanks) here, then CICS will pass control to the program having that name (which must be on the library and specified in the PPT), it is your responsibility to ensure that the abend handler program properly terminates your task, etc.

    PF6 will pop up a small window which allows you to select which of the standard nine functions you wish to have included in this MMP when it is generated. For this project we will accept the default (all nine functions). In other applications you may wish to suppress some functions to optimize program sizes, or for security reasons.

    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

      M A G E C Repository
      MMP Definition Screen
      MMP# 600 

    MMP Description: VACATION/SICK/COMP DAYS______ 
      The MMP can be generated to
    Mask Number: 600  include some, or all, of the nine
      standard functions.
    Abend Handler: ________  (CICS ONLY)
      Press PF6 to review or modify
    Programmer: YOUR.NAME______  the list of functions to be in-
      cluded in this MMP.
    Date Generated: 

    Time Generated: 

    The information above was copied from the SHD Record just added

    Figure 02 -- MMP Header Definition Screen

    STEP 2 --  Paint Screen


    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).


     TSKLST 600                            PF8 = Next Page-- PF5 Key = Page 1


    ...............T A S K......................... PAGE 1  .....STATUS......
     Position the Cursor on an Item and Press ENTER to Select it, Press PF2 for
      Item Description  -OR-  PF1 FOR HELP

    Figure 03 -- Task List Screen


    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.

    MSKDEF 600 
      M A G E C  Development Process Selection

    Press PF7  -  for the semi-automated development process which allows you to
      provide Cobol code to construct the key(s) to use to join
      additional Data Classes to the primary Data Class.

    Press PF8  -  for the fully-automated development process which generates the
      join logic completely based upon your selections and using the
      Domain definitions for Data Items.

    Press PF3  -  to return to the manual screen painter which provides complete
      flexibility to manually draw a screen, define attributes, and
      code join logic.

    Choose the level of automated development you desire. The fully-automated
    process is preferred. The semi-automated process is necessary only if your
    data has not been defined using MAGEC's Domain facility.

    Figure 04 -- Process Selection Screen

    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.    

     JOIN01  600
    Date: 04/06/1990  M A G E C  Time: 13:09:10
      Automatic Join Facility - Elements Selection List
      Application: 600  -  VACATION SICK/COMP DAYS 

    Elements for Primary Data Class :  Additional Elements Selected:
      VAC  -  MAGEC Vacation Demo File  1
    1 VAC01 MAGEC Vacation Demo Record  2
    2  3
    3  4
    4  5
    5  6
    Press PF5 for JOIN Candidates  ==> 15 more ELEMENTS may be Selected <==
    Press PF6 When Selections are Complete
    Move the CURSOR to the Desired ELEMENT and Press PF10 to Select ELTs for DELETE

    Figure 05 -- Element Selection List

    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.

     JOIN02 600                              PF8=Page Forward : PF5=RESTART Browse
      M A G E C  -  Candidate Elements for JOIN

      Element  -------Description--------------  Key Type
      SIF01  MAGEC Sign-In File Record  Full
      END OF LIST  PF5 Key = Page 1

    Press PF7 to Page Backward  == > 15 More Elements may be Selected <==
    Press PF5 to RESTART Browse  Press PF3 to Return to JOIN01 Screen
    Move the CURSOR to the Desired ELEMENT and Press ENTER to Select for JOIN

    Figure 06 -- Element Pick-List 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

    JOIN03 600                              PF8=Page Forward : PF5=RESTART Browse
      M A G E C  -  Elements Assoc. with SIF01

     DCL  Element  --------- Description ------------  Status
     SIF  MAGEC Sign-In Security File
     ***  SIF01 [Key] MAGEC Sign-In File Record  Selected
      SIF02  Security Name Info.
      END OF LIST -- PF5 Key = Page 1

    Press PF7 to Page Backward  == > 14 More Elements may be Selected <==
    Press PF6 When Selections are Complete  Press PF3 to Return to JOIN02 Screen
    Move CURSOR to Desired ELEMENT -- ENTER=Select for JOIN - PF4=UN-Select for Join

    Figure 07 -- Associated Element Pick-List

    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.

     JOIN01  600
    Date: 04/06/1990  M A G E C  Time: 13:09:10
      Automatic Join Facility - Elements Selection List
      Application: 600  -  VACATION SICK/COMP DAYS 

    Elements for Primary Data Class :  Additional Elements Selected:
      VAC  -  MAGEC Vacation Demo File  1  SIF01 MAGEC Sign-In File Record
    1 VAC01 MAGEC Vacation Demo Record  2
    2  3
    3  4
    4  5
    5  6
    Press PF5 for JOIN Candidates  ==> 14 more ELEMENTS may be Selected <==
    Press PF6 When Selections are Complete
    Move the CURSOR to the Desired ELEMENT and Press PF10 to Select ELTs for DELETE

    Figure 08 -- Element Selection List


    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-LAST-NAME 03
    again, from the first page: (PF7 key pages backward)
    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).


     PAINT2  600                            PF8=Forward / PF7=Backward / PF5=Top
    Grp  Key  CURSOR-SELECT Data Items  Ocr  Selected
    + +  T O P  O F  L I S T  + +
    Elt VAC01  04 VAC01-ELEMENT  X(00198)
    Grp Key  05 VAC01-KEY  X(00018)
      _ Key-1  07 VAC01-EMPNUM  9(09)
      Key-2  07 VAC01-SPACES  X(00009)
      05 VAC01-EARNED-VACATION  S9(05)V9(02) COMP-3
      05 VAC01-TAKEN-VACATION  S9(05)V9(02) COMP-3
      05 VAC01-EARNED-SICK-DAYS  S9(05)V9(02) COMP-3
      05 VAC01-TAKEN-SICK-DAYS  S9(05)V9(02) COMP-3
      05 VAC01-EARNED-COMP-DAYS  S9(05)V9(02) COMP-3
      05 VAC01-TAKEN-COMP-DAYS  S9(05)V9(02) COMP-3
      05 VAC01-COMMENT  X(00050)  3X
    Elt SIF01  04 SIF01-ELEMENT  X(00264)
    Grp Key  05 SIF01-MASTER-KEY  X(00006)
    Grp Key  07 SIF01-LOVALU  X(00002)
      Key-1  09 SIF01-KEY-PREFIX  S9(04)  COMP

    ENTER = Select item  PF4 = un-select item  PF6 = Field Selection Completed
    PF10 = un-select ALL items Press PF3 to Return to JOIN01

    Figure 09 -- Data Item Selection Screen


    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.


    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.

     PAINT3  600


      Select an Option using the Cursor, and Press ENTER

      OPTION 1 = LIST/2 - double-space, one item per line
      OPTION _2 = LIST/1 - single-space, one item per line
      OPTION 3 = COMPACT/2 - double space, multiple items per line
      OPTION 4 = COMPACT/1 - single-space, multiple items per line
      OPTION 5 = SUPER-COMPACT - single-space, multiple items per line, NO TITLE
      OPTION 6 = LIST/3 - one item perline, double-space, left justified prompts
      OPTION 7 = LIST/4 - one item per line, single space, left justified prompts


    Figure 10 -- Format Selection Screen



    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.


     PAINT6  600
      M A G E C
      Automatic Logical Join

     Enter Code to Build Key Value into SIF01-MASTER-KEY
      move zero to sif01-key-prefix.
      move vac01-empnum to sif01-empnum.


     AFTER: VAC01
      press PF10 to bypass to MSKDEF

    Figure 11 -- Key Value Screen


    MSKDEF - Your New Mask

    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):

    MSKDEL 600                 and press ENTER

    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:

    VACSEE 123456789                 to SEE employee # 123456789's data

    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.


     MSKDEF 600                             Press PF10 to MSKCREAT
    @Date:@ __________>  @VACATION/SICK/COMP DAYS> @Time:@XX:XX:XX>

      @First Name@_______________>
      @Last Name@_________________________>
      @Hire Date@________>
      @Earned Vacation@_________>
      @Vacation Taken@_________>
     @Sick Days Earned@_________>
      @Sick Days Taken@_________>
     @Comp Days Earned@_________>
      @Comp Days Taken@_________>
    @Comment (3 lines)@__________________________________________________>

    LAST GEN=93 08 05 --LINE: 4=DUP 5=ERASE 6=MOVE 13=DEL 14=INS
    LAST UPD=93 06 22 2494 BYTES MAX, nnnn USED, nnnn LEFT  PF24=POP-UP HELP

    Figure 12 -- Your New Mask Displayed

    MSKDEF - Modifying an Attribute

    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.

     MSKDEF  600                             --Press ENTER  to Update Field--
    @Date:@__________>  @VACATION/SICK/COMP DAYS> @Time:XX:XX:XX>

      @First Name@_______________>
      @Last Name@_________________________>
      @Hire Date@________>
      @Earned Vacation@_________>
      @Vacation Taken@_________>
     @Sick Days Earned@_________>
      @Sick Days Taken@_________>
     @Comp Days Earned@_________>
      @Comp Days Taken@_________>
    @Comment (3 lines)@__________________________________________________>

    Press PF13 for Hardcopy
    Press PF16 to Copy Field to Buffer Press PF17 to Paste data from buffer
    Press PF2 for Field-Level Help Press PF3 to Escape to MSKDEF

    Figure 13 -- Screen Field Selected for Change


    STEP 3 -- Customization

    Optional Customization

    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.


    STEP 4 --  Generate & Compile

    TSKLST After Auto-Paint

    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.    

    TSKLST 600                             PF8 = Next Page --PF5 = Page 1


    ...............T A S K......................... PAGE 1  .....STATUS......
     Position the Cursor on an Item and Press ENTER to Select it, Press PF2 for
      Item Description  -OR-  PF1 FOR HELP

    Figure 14 -- Task List Status After Auto-Paint

    STEP 5 --  Demo & Test

    New Copy of MMP

    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:

    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.

    Testing Maintenance & Inquiry Functions

    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.

    VACSEE 01
    Date: 08/12/1988  VACATION/SICK/COMP DAYS Time: 10:15:04

      Emp# 000-00-0001
      First Name Harry
      Last Name Houdini
      Hire Date 12/11/45
      Earned Vacation  14.50
      Vacation Taken  2.25
      Sick Days Earned  124.50
      Sick Days Taken  3.00
      Comp Days Earned  2.00-
      Comp Days Taken  .00
     Comment (3 lines) Heavy into Escape literature.
      Likes to be submerged while handcuffed and
    strait-jacketed in a coffin-like vault.

    Press PF4 for browse (LOC) screen Press PF13 for Hardcopy
    Press PF16 to Copy field to buffer  Press PF17 to Paste data from buffer
    Press PF2 for field-level HELP

    Figure 15 -- Testing Maintenance & Inquiry Functions

    Testing Browses

         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

     VACLOC 01                              END OF LIST - PF5 = Restart/PF7=Backward

    Emp #  First Name  Last Name  Hire Date Earned Vacation

    000-00-0001 Harry  Houdini  12/11/45  14.50
    000-00-0002 Uri  Geller  02/13/81  125.00-
    000-00-0003 Merlin The Magician  01/21/80  5.25
      ++++ 03 Records Scanned, 03 Displayed so far - Page 1 ++++

    KEY 1 = Employee # (9-digits) Press PF13 for Hardcopy
    You may Position the CURSOR on an item and Press ENTER to SEE it
    (Browsing Forward) or Press PF4 to CHG it

    Figure 16 -- Testing Browse Functions

    STEP 6 --  Documentation

    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.

    Multi-Level HELP

    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.

    VACSEE 01
    Date: 08/12/1988  VACATION/SICK/COMP DAYS Time: 10:15:04

      Emp# 000-00-0001
      First Name Harry
      Last Name Houdini
      Hire Date  12/11/45
      Earned Vacation  14.50
      Vacation Taken  2.25
      Sick Days Earned  124.50
      Sick Days Taken  3.00
      Comp Days Earned  2.00-
      Comp Days Taken  .00
     Comment (3 lines) Heavy into Escape literature.
      Likes to be submerged while handcuffed and
      strait-jacketed in a coffin-like vault.

    Press PF4 for browse (LOC) screen  Press PF13 for Hardcopy
    Press PF16 to Copy field to buffer  Press PF17 to Paste data from buffer

    Figure 17 -- Testing HELP Keys

    STEP 7 --  Put into Production


    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.

    Development is Done

    What Have You Produced?

    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.

    Appendix A --  Sample Files

    VAC Data Class

    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:

    VAC00 36-byte audit-stamp

    VAC01 234-byte vacation data

    There is one key for the VAC data class:

    VACK1 9-digit employee# + 9-byte blank padding

    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:

    LBRSEE VAC01-C                

    To view the data class definition for VAC enter:

    DCLSEE VAC                

    To view the key definition enter:

    KYFSEE VACK1                

    To view the element defintions enter:

    ELTSEE VAC01                

    ELTSEE VAC00                

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

    DITLST VAC01                

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

    SIF Data Class

    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:

    SIF00 36-byte audit-stamp

    SIF01 234-byte security information data

    There is one key for the SIF data class:

    SIFK1 2-byte prefix + 9-digit employee#
    entire key is binary (6-bytes long)

    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:

    LBRSEE SIF01-C                

    To view the data class definition for SIF enter:

    DCLSEE SIF                

    To view the key definition enter:

    KYFSEE SIFK1                

    To view the element definitions enter:

    ELTSEE SIF01                

    ELTSEE SIF00                

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

    DITLST SIF01                

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


    Appendix B --  Attributes

    3270 Attributes

    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:

    LBRSEE MAGEC003                

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

         Character     Letter       Meaning

         Position      Value        of Letter Value

              1          P          Protected

                         S          Skip-Protected

                         U          Unprotected

              2          A          Alphanumeric

                         N          Numeric Shift (keyboard)

              3          D          Displayable

                         N          Non-displayable

              4          R          Regular Intensity

                         H          High-intensity

              5          N          Non-selector-pen detectable

              6          M          Modify Data Tag ON

                         F          Modify Data Tag OFF


    Table of Attributes

    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.

         Symbolic         Cobol Name    Actual Code

           Name         (in MAGEC003)   Value     

         UANRNF            ATUANRNF     <

         UADRNF            ATUADRNF      b (blank)

         UADHNF            ATUADHNF     H

         UANRNM            ATUANRNM     (

         UADRNM            ATUADRNM     A

         UADHNM            ATUADHNM     I

         UNDRNF            ATUNDRNF     &

         UNDHNF            ATUNDHNF     O

         UNDRNM            ATUNDRNM     J

         UNDHNM            ATUNDHNM     R

         PANRNF            ATPANRNF     %

         PADRNF            ATPADRNF     -  (dash)

         PADHNF            ATPADHNF     Y

         PANRNM            ATPANRNM     _ (underscore)

         PADRNM            ATPADRNM     /

         PADHNM            ATPADHNM     Z

         SANRNF            ATSANRNF     +

         SADRNF            ATSADRNF     0 (zero)

         SADHNF            ATSADHNF     8

         SANRNM            ATSANRNM     ' (apostrophe)

         SADRNM            ATSADRNM     1 (one)

         SADHNM            ATSADHNM     9

    Appendix C --  Edit Type Codes

    Automatic Editing

    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:

  • AlphaNumeric
  • Numeric
  • Dates
  • 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.

    Table of Edit Types

    AlphaNumeric Edit Types:

    X Miscellaneous fields, any characters will be accepted. Example: company name, comments.

    b Same as X.

    A Alphabetic (A-Z and blank) characters only. Example: person's name, city name.

    U Uppercase. Any characters will be accepted as valid, lowercase alphabetics will be converted to uppercase by MAGEC.

    T Table lookup. Same as U plus MAGEC will validate entry against a lookup table.

    W Where to display a description from a lookup table. Used in conjunction with a T field. MAGEC moves the description from the found entry in the table to a W field.

    P Pattern edited alphanumeric field.

    Numeric Edit Types:

    N Numeric, MAGEC will pad with leading zeros.

    S Numeric, MAGEC will suppress leading zeros.

    = Same as S, plus trailing minus sign.

    Z Same as S, plus comma insertion.

    - Same as Z, plus trailing minus sign.

    $ Same as Z, plus floating dollar sign.

    # Pattern edited numeric field.

    Date Edit Types:

    M MM/DD/YY or MM/DD/CCYY (2 or 4-digit years).

    D DD/MM/YY or DD/MM/CCYY (2 or 4-digit year).

    Y YY/MM/DD or CCYY/MM/DD (2 or 4-digit year).


    12345.5 -or -

    1,234.50 -or-

    $1,234.50 etc.

    Appendix D --  Deleting Sample Online Application

    If Sample is Already Done

    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.

    enter SHDPUR 600 Message will tell you to press PF14

    press PF14 All customization will be deleted

    Mask will be deleted

    All selections will be removed

    MMP header will be deleted

    Mask copybook will be deleted

    Screen header will be deleted

    Appendix E --  Most Used Online Functions

    Developer's Functions

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

    ALGLST mmm Directory of custom algs. for mask mmm
    ALGxxx mmm/pppppppp/etc. Inquiry & maintenence for custom algorithms
    BCHPGM nnnB Create batch report program
    BCHLOC nnnB Locate batch report headers
    DBDITO Character/hex record display/update
    DBUTIL Character/hex record display only
    DOCxxx topic name Inquiry/maintenence for documentation
    ERRxxx eee Inquiry/maintenence for error msgs
    LBRxxx member/modifier Inquiry/maintenence for lib member
    LBRLST 1 List directory of library members
    MMPxxx nnn Inquiry/maintenence for MMP headers
    MSKDEF mmm Manual screen painting
    MSKDEL mmm Delete mask detail
    MSKDUP mmm Duplicate mask detail
    MSKCRE mmm Online Mask Create (vs. batch MSKCREAT)
    MSKSEE mmm Display generated mask
    MSKPOP Display Pop-Up help for Screen Painting
    PAINT1 mmm (thru PAINT7) Automatic Screen Painter
    RPTDEF nnnB Report Painter
    RPTDEL nnnB Delete report detail
    RPTDUP nnnB Duplicate report
    SCDLST mmm List locate headings for mask mmm
    SCDCHG mmm/row/col Change locate heading for field
    SCDTBL ttt Where-Used for Table number
    SQLCRE mmm Generate SQL customization code
    TBLLST ttt List lookup table entries
    TBLxxx ttt/cccc Inquiry/maintenance for table entry
    TOCLOC ttt List table of contents for lookup tables
    TOCxxx ttt Inquiry/maintenance for TOC of lookup tables
    TSKLST mmm Developer's task list
    VERZUN MSKmmm Version verification for application

    LEGEND: mmm Mask number (pattern: 9xx)
    xxx Standard nine suffixes (ADD, CHG, etc.)
    ttt Table number
    nnn MMP/MBP number (pattern: 9xx)
    pppppppp Insertion point name
    cccc 1 thru 16-character code
    eee Error number

    Program Function Keys used in Developer's Functions

    PF Keys (general)

    PF15           Exit MAGEC

    PF9            Swap Windows

    PF12           Return to TSKLST (from a development function)

    PF1            HELP key

    PF2            Field-level HELP

    PF16           Copy data to Copy/Paste buffer

    PF17           Paste date from Copy/Paste buffer

    PF24           Pop-Up short list from prior browse

    PF11           Help Index

    PF13           Hardcopy (if Spooler installed)

    PF8            Page Forward/Next

    PF7            Page Backward/Previous

    PF3            Escape back one level, or to low-level menu

    PF Keys in Pop-Up Window

    PF16            Copy data to Copy/Paste buffer, remove Pop-Up

    PF24            Cursor-select from short list, remove Pop-Up

    PF Keys in MSKDEF

    PF18           Change field

    PF19           Delete field

    PF20           Duplicate field

    PF4            Duplicate line

    PF5          Erase all fields on a line

    PF6          Move line

    PF21          Move field

    PF10          Go to Auto-Paint sequence (if no screen fields exist)

                  Execute online MSKCRE (if screen fields exist)

    PF13          Delete a blank line

    PF14          Insert a blank line

    PF24          Pop-Up help window

    PF Keys in PAINT2 and BCHPG2

    PF7          Scroll Backwards

    PF3          Return to PAINT1 or BCHPGM

    ENTER          Select item

    PF4          Unselect item

    PF6          Done selecting data items

    PF10          Unselect all items

    PF Keys in DBDITO and DBUTIL

    PF23           Display next 280 bytes of this record

    PF22           Display previous 280 bytes of this record

    PF8            Read next record (forward)

    PF7            Read prior record (backward)

    PF Keys in LBRxx and ALGxxx

    PF8            Page forward thru member

    PF7            Page backwards thru member

    PF20           Insert after line where cursor is positioned

    PF5            Bypass warning-level errors and update

    PF16           Copy a line (or many lines using CC - CC)

    PF17           Paste line or lines from Copy/Paste buffer

    PF Keys in PAINT1 and BCHPGM

    PF5            Bypass warning-level errors and continue

    PF Keys in RPTDEF

    PF18           Change field

    PF19           Delete field

    PF6            Return to BCHPGM screen

    PF21           Toggle between display/nondisplay fields

    PF22           Display next 80 columns of report (shift right)

    PF23           Display previous 80 columns of report (shift left)

    PF20           Add a field to the right of cursor

    Appendix F --  Universal Functions

    Logical Application 00's Functions

    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.

    OPTION Set session option for CLEAR and PA1 key

    **HELP Menu-driven review of help text

    **SWAP Swap windows (same as pressing PF9)

    **EXIT Exit MAGEC
    (same as pressing PF15)

    **PF01 thru **PF24 Simulate PF key entry

    **PA01 thru **PA03 Simulate PA key entry

    **ERR1 HELP (same as pressing PF1)

    **MENU High level menu

    ++MENU Intermediate level menu

    $$MENU Low level menu

    MSGSEE Display broadcast message

    BROWSE BACKWARD Set browse direction to backwards for LOC, SCN,
    and FND functions

    BROWSE FORWARD Set browse direction to forward for LOC, SCN, and
    FND functions

    CLEARS Display MAGEC logo screen

    SYSLOG ON Log on to MAGEC

    SYSLOG OFF Log off of MAGEC

    Appendix G -- Problem Solving Aids

    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.

    Error Messages in SERRMSG

    These messages are stored on the MAGEC ERR file and they include a 4-line description. You can press the high-level help key (PF1) whenever an error message is being displayed. Pressing PF1 will give you an online display of the explanations for your errors. You can produce a hardcopy list using the batch ERRLIST program, or you can display the error messages with their explanations online using the command:

    ERRSEE xxx (xxx is the error number)

    Error Messages In SCOMPL

    Certain error conditions display messages in SCOMPL. These are documented in the "Database Administration" chapter of the Programmer's Reference Guide.

    DBxx Abend Codes

    Various types of I/O-related errors may be detected by MAGEC's I/O module which will result in the I/O module's aborting the task and issuing an abend code as: DBxx. These codes are documented in the "Database Administration" chapter of the Programmer's Reference Guide. There is usually also an explanatory message issued to either the user terminal, the console, or both. I/O errors on a PC are often caused by insufficient memory, causing a file OPEN to fail for lack of adequate space for buffers.

    DB17 Abend Code

    This return code can result from several causes, but it usually means that the definition of a file key does not match the definition given to MAGEC. For example: an alternate key might specify No Duplicates to the access method and Duplicates Allowed to MAGEC, or the offset/length given to MAGEC might not agree with the definition to the access method, or the number of keys might be different, et cetera. Also check that fixed-length/variable-length and record length specifications agree.

    MSKCREAT Errors

    When the batch MSKCREAT jobstream is executed, it produces a listing which serves as an audit trail of what has been processed and also displays any appropriate error message(s). If you are experiencing problems which seem to involve the screen display or references to screen fields in your program you should look at the MSKCREAT printout to see if it indicates any problems. If any errors are found, MSKCREAT will not catalog the new mask copybook On a PC this "print" output might have been routed to your screen, rather than to print. You can execute MSKCREAT with the print routed to LPT1 or LPT2 if necessary. To do so use the command: MSKCREAT nnn LPT1 (or LPT2, as appropriate).

    MSKCRE Errors

    When you execute the online MSKCRE function, instead of the batch MSKCREAT jobstream, error messages will be displayed to your screen instead of being printed. If any error is encountered processing will not complete, just as in the batch MSKCREAT.

    MMPCREAT Errors

    As the batch MMPCREAT jobstream is generating your MMP's it edits and validates all specifications. If any errors are encountered MMPCREAT will print error messages in the printed output which includes an audit trail of its processing. If you experience errors in executing or compiling the generated program you should check the printed output from MMPCREAT to see if any errors or warnings were displayed. On a PC this output mignt have been routed to your screen, rather than to print. You can execute MMPCREAT with the print routed to LPT1 or LPT2 if necessary. To do so use the command: MMPCREAT nnn LPT1 (or LPT2, as appropriate).

    MBPCREAT Errors

    -same as for MMPCREAT Errors-

    Data Definition Errors

    If you suspect that your application might be executing using a non-current definition of a data Element, check the version verification information online using the command:


    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.

    Business Rule Errors

    If you have made, or intend to make, changes to a Business Rule, you should use the online where-used facility to ascertain what applications will be affected. To do so, enter the command:

    RULUSE eeeee (eeeee is an Element name)

    Referential Integrity Rule Errors

    -same as for Business Rule Errors-

    MAGEC System Program Abends

    One of the most likely causes for unexplained abends of MAGEC's own programs would be corruption of the dictionary files. To audit the dictionary, producing a comprehensive report of errors or suspected errors, execute the batch DDAUDIT utility. Refer to the "Offline Utilities" chapter of your Programmer's Reference Guide for control card and execution instructions.

    Note that it is normal for some of MAGEC's batch programs to force an abend in certain circumstances. In these cases you will usually receive a "decimal divide exception" (OC9) accompanied by an error message displayed with the printed output; or you may receive an "operation exception" (0C1) with the PSW pointing (in the dump) to an error message. The most common place where you might experience this is in the MMPCREAT or MBPCREAT jobstreams when they encounter specification errors which preclude the proper generation of a program. You might also receive an abend from the online control program if certain unrecoverable errors are detected, especially errors involving corrupted screen mask control sequences.

    Suspected Dictionary Errors

    Execute DDAUDIT to verify the integrity of your MAGEC dictionary. Refer to the "Offline Utilities" chapter of your Programmer's Reference Guide for control card and execution instructions.

    MMP Errors

    If you think that your MMP is operating incorrectly, and do not know why, it might be because you are executing an old version of the program. It might also be because your program was compiled using an old version of the mask copybook, or an element copybook. To quickly verify the versions of those components of your MMP, use the online version verification by keying the command:

    VERZUN MMPnnn (nnn is your MMP number)

    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.

    MMP Abends

    If you are using a PC, you can usually debug abend situations easily by invoking MAGEC using the TRACE command (instead of TS01), and executing your transaction. When the screen displays your Cobol code, just press the "T" key to let the program execute while simultaneously tracing on the screen. When it reaches the abend, it will stop. You will see the instruction on which the abend occurred and can view the contents of storage to determine the cause. This works well for "data exception" abends, and for some others as well.

    Table Lookup Usage

    If you wish to know which applications are using a given MAGEC Lookup Table, you can find the answer online using the command:

    SCDTBL nnn (nnn is the table number in question)

    Data Usage

    In addition to the DCLDOC utility, you can also use the where-used facilities of the MAGECLBR utility to produce hardcopy reports. You can report usage for Data Items, Elements, copybooks, tables, and even generic character strings. Refer to the "Offline Utilities" chapter of your Programmer's Reference Guide for control card and execution instructions.

    Insertion Point Mis-Use

    A number of customization errors can be avoided or corrected by simply reviewing the appropriate areas of the "Insertion Points" chapter of your Programmer's Reference Guide. The "cautions" for each insertion point were compiled based upon errors encountered by other people. There is a good chance that an error you experience might not be original and that you can benefit from their pain.

    Compiler Diagnostics

    If you have received error messages from the Cobol compiler, you can follow a simple procedure to get directly to the coding containing the errors. First look at the line numbers shown immediately to the left of each error message in the error report at the end of your compile listing. Then find those line numbers in the body of the source listing. You will notice that MAGEC has inserted "markers" above, below, and in the right margin (columns 73-80) of all of your customization coding. Since the probability is very high that any errors will be in the customization code, rather ,than in the generated code, this will help you to go directly to the customization coding to correct the errors. The markers identify the mnemonic insertion point name plus any modifier you have used (i.e. EDIT/BADDATE, or JOIN/01-SIF). You can use the online ALGSEE function to display and update the customization coding, i.e.:

    ALGSEE 600/JOIN/01-SIF  

    Bad Data on Files

    If you suspect that there is bad data on your data files, you can verify it by using the online DBDITO facility to view or update virtually any data--if you are authorized. If your are getting a Data Exception abend and suspect that it is caused by non-numeric data in data items which are defined as being numeric, you can turn on the VERIFY option (on the SHDxxx screen, or BCHPGM screen) for your application. The VERIFY option will usually protect your application from abending and enable you to use your [online] application to correct the bad data on file. It cannot protect against data exceptions occurring in your customization coding, though. Refer also to the topic "MMP Abends" earlier in this appendix.

    PC Jobstream Will Not Run

    One of the most common reasons for the failure of MAGEC's jobstreams to not run, or to not run correctly, on the PC is an incorrect PATH specification. All batch operations are executed via .BAT files which are all stored in the \MAGxx\JCL directory. When attempting to execute them you must include \MAGxx\JCL in your path and you must not include \MAGxx in your path. This is because there are certain .EXE files in \MAGEC which have the same names as .BAT files in \MAGxx\JCL. Remember, the "current directory" (CD) is always implicitly the first directory in your path; thus, you must not have \MAGxx as your current directory when you attempt to execute a MAGEC jobstream.

    Terminal Unable to Access MAGEC

    If certain terminals are having difficulty accessing MAGEC while others seem to work OK, the problem may be that some records on the TWA file have become corrupted. This could be caused by an errant online program, or by some other problem.

    Each terminal has a set of records (the number of records will vary) on the TWA file. The TWA file key is eight bytes long, the first four bytes being the terminal ID. Data is saved in these records to support pseudo-conversational processing, online help, window swapping, and many other intrinsic MAGEC features. If, somehow, these records cannot be accessed because of file errors, index errors, or if they just have garbage data stored in them, it is possible that the terminal for which those records exist might not even be able to access MAGEC. MAGEC might issue a message indicating that an error has occurred accessing the TWA file, or that the files are not open, or some other fatal error message.

    You can purge the TWA file of all records for a given terminal using the online command:

    TWAPUR tttt

    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.

    Program Runs Differently in Other Environment

    If you have migrated an application from one environment to another using APUNLOAD / APLOAD and it seems to work differently in the new environment, there are several common causes to look for. First, the data on your files may be different and it may be perfectly normal to get different results. Second, the release level of your MAGEC systems may be different. Third, you may find some differences caused by using various Cobol compilers. MAGEC attempts to protect you from the peculiarities of various Cobol implementations, but 100% compatibility is not always possible. Fourth, you may be experiencing the effects of different collating sequences in ASCII and EBCDIC. Fifth, the configuration and available memory on microprocessor and network systems may affect execution. In OS/2 or MS-DOS, check the CONFIG.SYS and/or AUTOEXEC.BAT files against the recommendations in MAGEC's (and your Cobol compiler's) installation guides. Be sure your mapping is correct if accessing a network server. Finally, check the data definitions in the MAGEC Repository, especially the KYF DD Name and Drive ID on a LAN. Remember the environment setting for LANDRV and LCLDRV determine MAGEC's defaults for locating files.

    Appendix H -- Viewing the Cobol

    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.

    Appendix I - MODELWIN

    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:

    1. In the SHD record, specify "MODELWIN" in the 'Use Model:' field to indicate to MAGEC that you are creating a window application. (Refer to the Define Application section of the Tutorials manual or to the "Screen Painting" section of the Programmer's Reference Guide for explanations of all SHD screen fields.) Specify the MMP record as usual.

    2. Choose 'Paint Screen/Define Mask Detail' from the 'TSKLST nnn' screen (or just use the command: "MSKDEF nnn") to enter the screen painter. It will sense that you are using MODELWIN and will auto-generate the window border for you.

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

    Field drawn outside window border

    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.

    3. Verify that the control card into MMPCRE (MMPCRE.RDR file on a PC) contains the -MAGECINC &MDL card in lieu of the old -MAGECINC MOD&TYP card as in earlier versions of MAGEC. When MMPCREAT runs, you should verify that MODELWIN is the first -MAGECINC listed in the MMPCREAT listing.

    4. If you wish to call the pop-up window from another function, perhaps a full-screen function, refer to the Attach / Detach feature of MAGEC which is discussed in Appendix R of the Customization section of this Tutorial manual.

    Appendix J - Selecting Data

    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.

    Appendix K - GUI Applications

    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

    Background Color

    This is the color of the panel's background. Each user can set his/her profile for preferences regarding text colors for any given panel background. There are sixteen colors to choose from. You can mouse-click the Background Color specification box to pop up a scrolling list of color codes with descriptions.

    Static Text Color

    This is the color for static text, such as headings, on your panel. You can select from the sixteen possible colors.

    Border Type

    This is the type of border you wish to be displayed around enterable (unprotected) data fields on the panel. You may specify that you want a 3-D border, which gives the appearance that the enterable fields are recessed into the panel, a line border, which simply appears as an outline around the fields, or no border at all. If your panel has a lot of enterable fields crowded close to one another, it may be best to specify no border to avoid further cluttering the display.


    You can select a default toolbar, which includes all the standard buttons, or a custom toolbar, which is the standard buttons less any you choose to exclude, or no toolbar at all. The toolbar is placed at the bottom of your panel. For most applications the standard default toolbar is a good choice.

    Tool Icons

    If you choose "custom toolbar" MAGEC will prompt you with each of the standard buttons (showing you the button with its icon and a brief description to the right of it) and ask you to respond with a Yes or No as to whether you want each button included in the toolbar for this panel. When you begin there will be an empty toolbar shown at the bottom of your screen. As you choose buttons, they are moved into the toolbar so that you can see how it will appear on the panel.

    You might wish to refer to the User's Guide, Appendix B for a more detailed description of the toolbar buttons.

    Doing Development in GUI Mode

    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.

    Graphical Cobol Customization

    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.